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iNTKOUUCTlQN 


I M lUDDIlcrnuN 


Atitif'inbly Language Whys and Wherefores 


yomc! of yon inay ask "What: is Assembly Language?" or do I 
need to use Assembly Language^ BASIC suits me fine." While 
we do not have the space here to do a treatise on the sub- 
jeci; j ve will attempt to briefly answer the above questions* 


Computer languages are often referred to as "high level" or 
"low level** languages. BASIC, COBOL, FORTRAN and PASCAL are 
ail high level languages* A high level language Is one that 
usally uses English—like words (commands) and may go through 
several stages of interpretation or compilation before final¬ 
ly being placed in memory* The time this processing takes is 
the reason BASIC and other high level languages run far 
slower than an equivalent Assembly Language program. In 
addition, it normally consumes a great deal more available 
memory* 


From the ground up, your computer understands only two 
things, on and off. All of its calculations are handled as 
addition or subtraction but at tremendously high speeds. The 
only number system it comprehends is Base 2 (the Binary Sys¬ 
tem) where a 1 for example is represented by 00000^01 and a 2 
is represented by 00000010, 


The 6510 microprocessor (the 6510 is equivalent to the 6502) 
has five S^bit registers and one 15—bit register. All data 
is ultimately handled through these registers by a machine 
language program. But even this lowest of low--ievel code 
requires a program to function correctly. This "program" is 
hard wired within the 6510 itself. The microprocessor pro¬ 
gram functions in three cycles: it fetches an instruction 
from memory in the computer, decodes It and executes it. 
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These Lnscructions exist in tTieTiiory as one^ two or tlirct? hyii^ 
groeps. A byte contains 8 binary bits of data and is usn.i 1 I y 
notated in hexadeciinal (base 16) form. Some early oilerurndi 
puters allowed data entry only through 8 front panel 
switches^ each of which when set on or off would combi nt' lit 
produce one binary byte. This required an additional progtam 
in the computer to monitor the switches and store the byte hi 
memory so that the 6510 could Interpret It. 

At the next level up, the user may enter his/her data in thi* 
form of a three character mnemonic (the '*m“ Is silent), a 
type of code whose characters form an association with !:hc 
microprocessor operation. For exampler LDA is a mnemonic 
which represents *'LoaD the Accumulator”- The Commodoii' 
monitor cartridge add--on has a mini-assembler that permits 
simple Assembly Language programming. 

But even this Is not sufficient to create a long and compre¬ 
hensive program* In addition to the use of a three charactrM 
mnemonic, a. full fledged assembler allows the programmer In 
use labels, which represent an as yet undefined area oi 
memory where a particular part of the program will be stored. 
In addition, an assembler will have a provision for llur' 
numbers, similar Co those in a BASIC program, which in turn 
permits the programmer to Insert lines into the program aufl 
perform other editing operations. This Is what MERLIN Is nil 
about. 

Finally, a high level language such as BASIC Is Itself nn 
assembly program which takes a command such as PRINT and 
reduces it by tokenlztng to a single byte before storing It 
In memory. 

Before using this or any other assembler, the user Is expect¬ 
ed to be sotnewhat familiar with Che 651^ architecture, modps 
of addressing, etc. This manual is not intended to te.ich 
Assembly Language programnilag * Many good books on 65 L0 
assembly programniing (which is nearly identical to 650!? 
assembly programming) are available at your local books to rrv. 
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systi:m iu:(;iinti:Mi':NTS 

* 64k Commodore 64 

* Diak Drive 


OkTtONAL: 


* DATA20 Videopack80 

* VIC-10L1A RS232 cartridge 
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BEGINWERS GUIDE TO USING MERLIN 


HI:(.INN]:KS guide to using merlin 


By T- ReCCCsen 

thnr.r, iiiid demonstrations for the beginning MERLIN programmer- 


I Mt.riHluction 

Tlic purpose of this section is not to provide Instrucclon in 
naaembly langaage programmings It la to introduce MERLIN to 
jjtogrammers new to assembly language programming In general, 
and MERLIN In particular. 

Many of the IfERLIN commands and functions are very similar In 
operation. This section does not attempt to present demon¬ 
strations of each and every command option- The objective is 
to clarify and present examples of the more common opera¬ 
tions, sufficient to provide a basis for further independent 
study on the part of the programmer. 

A note of clarification; 

Throughout the MERLIN manual, various uses are made of the 
terms '"mode" and "module'*. 

In this section, "module** refers to a distinct computer 
program component of the MERLIN system. There are five 
MODULES: 

1. The EXECUTIVE 

2. The EDITOR 

3. The ASSEMBLER 

4. The SYMBOL TABLE GENERATOR 
5* The MONITOR 
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Each module is grouped under one of the three CONTHOE. 

L) The EXrXUTIVE, abbreviated EXEC and indicated by Mii‘ 
pr oinp t * 

2) The EDITOR, indicated by the prompt. 

3) The MONITOR, indicated by the prompt, 

EXECUTIVE CONTROL MODE 
Executive Module 

EDITOR CONTROL MODE 
Editor Module 
Assembler Module 
Symbol Table Generator Module 
Monitor tiodule 

The term "mode" may be used to indicate either the current 
control mode (as Indicated by the prompt) or alternatively, 
while In control mode and subsequent to the Issuance of an 
entry command, the system Is said to be In '[entry commandj 
mode'. For example, while typing In a program after issuing 
the ADD command, the system is said to be 'in ADD mode'. 

Terminating [entry command | mode returns the system to con-* 
trol mode. 


Input 

Programmers familiar with some assembly and higher-level 
languages will recall the necessity of formatting the input, 
1-e* labels, opcodes, operands and comments must be typed In 
specific fields or they will not be recognized by the 
assembler program- 

In MERLIN, the TABS operator provides a seml-automntLc 
formatting feature. 
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liKClNNLltiS CUUJii TO USING MliKLIN 


UIm'u rntri iiiji pro^tMinSj cemember that during assenibly each 
I' ill L 111 * iiourco code causes a tab to the next tab field. 
Am jk L|«njnii\a 1 .1 at ion, let'‘s enter the following short routine* 


IT util Lhe very beginning: 

1* GOAD "H1:RHM“,8 and 

2. When the prompt appears at the bottom of the EXEC 
iiiude menu, type This instantly places the system in 

EDITOR control mode- 

,3. Since we are entering an entirely new program, type 

at the prompt and press RETURN (A = ADD). A "I" 

appears one line down and the cursor Is automatically 
tabbed one space to the right of the line number. The 
and all subsequent line numbers which appear after 
the RETURN key is pressed serve roughly the same purpose 
as line numbers in BASIC except that in assembly source 
code, line numbers are not referenced for jumps to sub¬ 
routines or in GOTO—like statements- 

. On line I, enter an (asterisk). An asterisk as the 
first character in any line is similar to a REM statement 
in BASIC - it tells the assembler chat this is a remark 
line and anything after the asterisk is to be ignored. 
To confirm this, type the title "DEMO PROGRAM I" after 
the asterisk and hit the RETURlN key. 

5 . After return, the cursor once again drops down one line, 
a "2" appears and the cursor skips a space* Now type a 
space, type "ORG", space, ":J8000", RETURN- 

6. On line 3; "CHROUT" , space, "EQU" , space, "$FFD2", 

and RETURN. 

/. On line 4, type "START", space, "LDA", space, "^$93", and 
RETURN- 

H. (J nc 5 “ type a space, "JSR" , space, "CHROUT", space, 

(srinlculoii) , "CLEAR THE SCREEN", RETURN. Semicolons are a 
cotivtMM. fun often used within comniand lines to mark the 
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start of cocnments. 


9* Line 6 - "DONE", space, 'RTS', RETURN* 

10. The program has been completely entered, but the sysn^m 
Is still In ADD mode. To exit ADD, Just press RETURN. 
The prompt reappears at the left of the screen, 

indicating chat the system has returned to control inndc. 


11- The screen should now appear like thlsr 


1 *DEMO PROGRAM 1 

2 ORG $3000 

3 CKROUT EQU $rFD2 

^ START LDA /?$93 

5 JSR CHROUT 

6 DONE RTS 


;CLEAR THE SCREEN 


Note that each string of characters has been moved to a 
specific field. There are four such fields, not Including 
the line numbers on the left. 


Field number..- 


One is reserved for labels. CHROUT, START and DONE are 
examples of labels. 

Two is reserved for opcodes, such as the MERLIN pseuflo-- 
ops ORG and EQU, and the 6510 opcodes LDA, JSR and RTS, 

Three is for operands, such as $8000, $FF02 and, In this 
case, CHROUT. 

Four will contain any comments. 

It should be apparent from this exercise that it Is not 
necessary to input extra spaces in the source file for 
formatting purposes. 
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III rniiiitii,i! y, iifitn’ iU(* line [lumbers: 

I) Du out sp^ce before a label- Press space once after 
label (or if there is no label, once after the line 
lUHLiber) for the opcode- 

<!) Space once after the opcode for the operand. Space 
once after the operand for the comment- If there is 
no operand, type a space and a semicolon. 


SynLem aiid Entry Commands 

has a powerful and complex built-in editor* Complex 
in the range of operations possible but, after a little 
practice, remarkably easy to use* 

Tlie following paragraphs contain only minor clarifications 
and brief demonstrations on the use of both sets of commands. 
All System and Entry commands are used in EDITOR Control Mode 
Immediately after the ' prompt* 

Tile STOP key or RETURN as the first character of a line exits 
the current [entry command} mode and returns the system to 
control mode when ADDing or If^SERTing lines. STOP exits edit 
mode and returns the system to control mode after Editing 
lines. 


The other System and Entry Commands are terminated either 
automatically or by pressing RETURN, 

Inserting and deleting lines in the source code are both 
simple operations. The following example will INSERT three 
new lines between the existing lines 5 and 6. 

I* After the " prompt, type (INSERT), the number ^6^, 

aiul press RETURN. All inserted lines will precede 
(nuTTierleally) the line number specified in the command. 

2. rnpiit an asterisk, and press RETURN* Note that INSERT 
tiiude Ikis not been exited. 

)* Rc|seaL step 2, 
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A . Type one space, 'TVA" , and press RETUKt^- 
On the screen is the foliowlng: 

:16 

6 * 

7 * 

8 TYA 

9 

5* Hit RETURN (or STOP) and the systenj reverts to CONTROL 
mode {':' prompt)- 

6 . LEST the source code. 


1 

*DEMO 

PROGRAM 1 

2 


ORC 

58!300 

3 

CUROUT 

EQU 

5 FFDZ 

4 

START 

LDA 

#$93 

5 


JSR 

CHROUT 

6 

* 



7 

■k 



8 


TYA 


9 

DONE 

RTS 



;CLEAR THE SCREEN 


The three new lines (6, 7, and 8) have been Inserted ^ and tlie 
subsequent original source lines (now line 9) have been 
renumbered. 


Using DELETE is equally easy. 

1. In control mode, Input "08", and RETURN. Nothing new 
appears on the screen. 

2. LIST the source code. The source listing is one line 
shorter. You^ve just deleted the ^TYA" line, and the 
subsequent lines have been renumbered. 
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II ]-j [HiniiUjU^ Lo delete a range of lines in one stepP 
I . Ill ctjniroi []iode j input '06,7' and RETUtiN* 
h'. LIST Llie source. 


Line!; 6 and 7 from the previous example^ which contained the 
hisurtcd asterisk comments^ have been deleted, and the sub- 
i;ei|nenc lines renumbered. The listing appears the same as in 
the subsection on INPUT, Step 11. 

Ihis automatic renumbering feature makes It IMPERATIVE that 
when deleting lines you remember to begin with highest line 
miiiibec and work back to the lowest. 


The Add, Insert, or Edit commands have several sub-commands 
comprised of CTRL-characters* To demonstrate, using our 
previous routine: 


i. After the ^ prompt, enter "E' (the EDIT command) and a 
line number (use "6^ for this demonstration), and hit 
RETURN. One line down the specified line appears in its 
formatted state: 


6 DONE RTS 


and the cursor is over the "D' in 


2. Type CTEIL-D. The character under the cursor disappears. 
Type CTRL-D again, again, and a fourth time, '"DONE^ has 
been deleted, and the cursor is positioned to the left of 
the opcode. 

3. Hit RETURN and LIST the program. In line 6 of the soaree 
code, only.the line number and opcode (RTS) remain. 


^1 . Repeat step I (above). 

5. This time, type CTRL-I (or the INSERT key). Don't move 
the cursor with the space bar or arrow keys. Type the 
word 'DONE', and RETURN. 


ii * 1,1 SI' the program. Line 6 has been restored. 
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If you are editing a single line, hitting RETUHf'I alone lo 
stores you to the control mode prompt. In step I (above) ^ II 
you had specified a range of lines (eKample: "*£3,6') vh I 1 e 
issuing the EDIT command^ RETURN would have called up tin* 
next sequential line number wichia the specified range. As 
the lines appear, you have the options of editing using Mm 
various sub^commands, pressing RETURN which will call up tho 
next line, or exiting the EDIT mode using STOP. NOTE: hit¬ 
ting RETURN will enter the entire line in memory, exactly nn 
it appears on the screen* 

The other sub-commands, (CTRL-charactecs) used under the EDIT 
command function similarly* Read the definitions in Sect L(ju 
3 and practice a few operations. 

Assembly 

The next step in using HEREIN is to assemble the source code 
Into object code. 

After the " prompt, type the edit module system command ASH 
and hit return. On your screen is the following; 

UPDATE SOURCE (Y/N)? 

Type N, and you will see: 

ASSEMBLING 


A9 93 
20 D2 FF 
8005 60 


1 

2 

3 

4 

5 

6 


*DEMO PROGRAM I 

ORG $8000 
CHROUT EQU $FED2 

START EDA //$93 

JSR CHROUT : CLE AR THE SCh K N 
DONE RTS 


--END ASSEMBLY, 6 BYTES, ERRORS: 0 
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\\\ in IN ii'HM u n.uiu.iI 


GUlDt; TO USING Mt::RLlN 


YHIlUL TAIUJ': - 

(VU’llAliliTECAL ORDER 



CIIKOIJ T 

= $ 1 ''ED 2 ? 

END 

=$8005 

/ RTAR'T 




lYMHOI, TARLE - 

NUMERICAL ORDER 



? START 

=58000 ? 

END 

=58005 

CUROUT 

= 5 EED 2 




IT instead of completing the above listing, the system beeps 
and displays ao error message, note the line number 
referenced in the message, and press RETURN until the 
’"ENU AS3EM&Ly.-o" message appears. Then refer back to the 
subsection on INPUT and compare the listing with step 11. 
Look especially for elements in incorrect fields. Using the 
editing functions you^ve learned, change any lines in your 
listing which do not look like those in the listing in step 
11 to what they should, then re-assemble. 

If ail went well, to the right of the column of numbers down 
the middle of the screen is the now familiar, formatted 
source code. 

To the left of the numbers, beginning on line 4, is a series 
of numeric and alphabetic characters- This is the object 
coda " the opcodes and operands assembled to their machine 
language hexadecimal equivalents. 

Left to right, the first group of characters is the routine's 
j starting address in meraory (see the definition of ORG in the 

^ section entitled "pseudo Opcodes - Directives"). After the 

colon are the numbers 'A9' and '93'- This is the one-byte 
hexadecimal code for the opcode LDA and the data byte $93. 

I 

, NiiTKi the label 'START' is not assembled into object code; 

viulLhor are comments, remarks, or pseudo-ops such as ORG. 
biich ulemeuts ace only for the convenience and utility of the 
^ |irng I aiiiinuv and the use of the assembler program, 

I 
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DUGlNNIiRS GUIDR TO llSlfJO HKlO.ir^ 


The next byte is a 20, which Is the value for '.JSR'. '\\u* iicsi 
two bytes (each pair of characters is one byte) on Hm* S 
bear a curious r esefiiblance to the last group of char act era un 
line 3; have a look. fn line 3 of the source code wc tu hi 
the assembler that the label ''CHROUT' EQUated with nddroSN 
$rFD2« In line 5, when the assefubler encountered 'CUROIIT' um 
the operand, it substituted the specified address. 1 ho 

sequence of the high and low-order bytes was reversed, Luiti 
Ing $FFD2 into D2 FF, a 6510 tnicroprocessor convention. 

The rest of the information presented should explain Itself, 
The total errors encountered in the source code was zero, niul 
six bytes of object code (count the bytes followUig tin* 
addresses) was generated. 


Saving and Running Programs 

The final step in using MERLIN is running the program. be¬ 
fore that, it is always a good Idea to save the source codo. 
Use the SAVE SOURCE command. Follow that with an OBJECT CO HE 
SAVE. Note that OBJECT CODE SAVE must be preceded by a sue 
cessful assembly, 

1. Return to control mode if necessary, and type RETURN. 

The system has quit EDITOR mode and reverted to EXE CUT TV F. 
(EXEC) mode. If the HERLIN system disk is still in the 
drive, remove it and insert an Initialized work disk. 

After the ‘'X' prompt, type 'S'" (the EXEC mode SAVE SOURCE 
command). The system is now waiting for a filenanu*. 
Type 'DEMOL', and RETURN. After the program has bnnn 
saved, the prompt returns, 

2. Type 'C' (-CATALOG) and look at the disk catalog. Tlu^ 

source code has beeri saved as a binary file titir-d 
*'DEH0l.S''- The suffix is a f ile-labe 111 ng 

convention which indicates the subject file Is sourc*' 
code. This suffix is automatically appended to the ruimn 
by the SAVE SOURCE command. 





tll iu IM Uuv\u M^iinuil 


fiLXlNNEKS GUIDE TO USING MEKLIN 


1. II1 1 kirniKM Lo return to EXEC mode and input '0^, for 
Uli IICG'r CODE SAVE. The object file should be saved under 
I 111 ' iiiimv. name as was earlier specified for the source 
Jilu, so press "Y*‘ to accept "DEMOl' as Che object name- 
there Is no danger of overwriting the source file because 
Llie suffix "',0' is appended to object code file names* 

While writing either file to disk, HERL1I3 also displays the 
iiddress parameter, and the length parameter, which Is the 
first address following the code. It's a good practice to 
Lake note of these* 

Return to EDITOR mode, type 'HON', and RETURN and the monitor 
prompt appears* Enter '8000G', and RETURN- The screen 
should clear* The demonstration, program was responsible for 
iLt 

Now you can return to the EXEC by typing 'Q' and hitting 
RETURN, or you can return to the editor with 'R' and RETURN* 
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Ml 1(1 IN llrM'iu 


EXECUTIVE MODE 


I.Xl.i IN I VI. MilDK 


Ml-' ivXKCUTIVE made is the program level provided for file 
ohH iM i'lhitu'o operations such as loading or saving code or 
lotalogitig the disk. The fallowing sections summarize each 
I niiii^iarul available in this mode ^ 


C:CATAliK; 

Use the space bar to make the Catalog pause, and any other 
key to restart. Use the STOP key to abort the Catalog. 


J.:hOAD 


I Ills command is used to load a source file from disk. You 
win be asked for the nacne of the file. You should not 
append .S since IfERLlN does this automatically. If you 
have hit *'L" by mistake, just press the space bar then RETURN 
and the command will be cancelled without affecting any file 
in memory. This also applies to the other EXECUTIVE mode 
comma lids, 

After a LOAD SOURCE (or APPEND SOURCE) command, you are 
autoiiiatically placed in the editor mode, just as if you had 
hit "'E'’. Subsequent LOAD SOURCE or SAVE SOURCE commands will 
tiisplay the last used filename. The cursor is placed on the 
first character and all the standard Commodore editing 
fuutures are in effect. Pressing RETURN will accept the 
fUename as displayed. The source will be automatically 
loaded at the correct address. 
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S:SAVE 


Use this to S3ve s biniiry source 
load comtriand, you do not specify 
hit RETURN to cancel the command* 
command above, the filename uHl 
may type RETURN to SAVE the same 
new filename * 


file to disk. As liv tin* 
the suffix ‘".S'" and yon cmu 
A s with the LOAD SUURLK 
then be displayed and yon 
filename, or substitute n 


NOTEr when a SAVE is done In the EXECUTIVE mode (or via 
SAV opcode, or Write, etc.), an error will result If the 
already exists. This can be avoided by starting the fll 
"@0:"'. Thus, the replacement file Is 
before the old file is scratched, so there must be room 
the file on the disk* 


the 

f U f' 

G name 
savGfl 
for 


This syntax may also be used for a LOAD but has no effect 
other than making the "S:- part of the default filename, 

CAUTION: occasional serious disk problems may result from 
using the "g:" syntax and this Is presumably due to a bug lii 
the Commodore operating system. Thus, unless you have ade¬ 
quate back ups for your files, it is suggested that this 
syntax be avoided and, instead, that you scratch files before 
re-saving them. 


A:APPEN0 


This loads in a specified source file and places It at the 
end of the file currently In memory. It operates In the same 
way as the LOAD SOURCE command, but does not affect the 
default file name* It does not save the appended file- you 
are free to do that if you wish* 


L8 


ni in I N ih.r I h Matnin \ 


EXHCUTlVt: MODfcl 


n iiKi VI. 

riiiv < oiiiKMiul util select the default disk device. The value 
lime* iiHifU 1)0 etjual to or greater than eight. 


i:-kI'ITI'Jt KlJ/ASH 

I'lii-i comma ad places you In the ED I TOR/ASSEMBLER mode. It 
aiil.ouiaLically sets the default tabs for the editor to those 
oppropelate lor source files. If you wish to use the editor 
to write an ordinary text file, you can type TABS and press 
HiniJUM to ssero all tabs* 


0:SAVi!: OBJECT CODE 

Tills coEEmand is valid only after the successful assembly of a 
source file. In this case you will see the address and 
length of the object code on the menu. As with the source 
achlress, this is given for information only. 

NOTE: that the object address shown is that of the program's 
URG (or $800^ by default) and not Chat of the actual current 
location of the assembled code (which is $8000 or whatever 
IIIMEM you have used). When using this command| you are asked 
for a name for the object file. 

Tills command automatically appends an "\0‘‘ to the Eilenaaie. 
I’hus you can safely use the same name as that of the source 
flic (without the "*S" of course). When this object code is 
saved to the disk its address will be the correct one, the 
one shown on the menu. When later, you LOAD it using the 
l.nAD ''EILE",8,.l syntax, it will go to that address, which can 
he anything ($800, $C000 etc.). 
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E^Ki^cuTiVK mu\ 


Q:QUIT 


This exits 
*'SYS 52000" 
which means 
memory* 


to BASIC* 
command ^ 
it will not 


You may re-enter nEKLlN by issuing the 
This re-entry will be a warm start, 
destroy the source file curreutly hr 


RrREAD TEXT FILE 

This reads text: files Into MERLIN. They are always appended 
to the current buffer. To clear the buffer and start fresh 
type NEW" in the editor. If no file Is In memory, the name 
given will become the default filename. Appended reads will 

not do this* 


When the read is complete, you are placed In the editor. If 
the file contains lines longer than 255 characters, these 
Tw ^ two or more lines by the READ routine. 

The file will be read only until it reaches IlIMEM, will 
produce a memory error if It goes beyond, and only the data 
to that point will rcnialn* 


W:WRITE TEXT FILE 

This writes a MERLIN file into a text file instead of a 
binary file. The WRITE command does not delete or scratch 
first. See CAUTION above regarding " syntax. 


C:RUN PROGRAM 

This command will LOAD and E.TECUTE the named program. The 
program must 'be In machine language (not a BASIC program) 
and must have the ".O" suffix as part of the current progr.nin 

"cTcl = Is Intended for using utilities such ,ns 

STRIP,0 , "XREF,0" or for running "SOURCEROR*0". 
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EXECUTIVE MODE 


K IMSK tlUNHANU 

riil't pirijihi tho compand to the "Error Channel". Examples of 
1 [ii riitlrd use are : 

X then V vlll do a disk verify 

X then S:FILE-0 will scratch '*FILE-0" 

X then RiNKWFILE.S OLDFILE-S will rename OLDFILE-S 

NOTE: the ,S or must be entered herej if any, and that 

quotes should not be used. Also, to prevent unintentional 
Initialisation, the N (New) comaiand is not supported. 

The address after "SOQECE" and *'OBJECT" on the menu give the 
start address followed by the address of the byte just BEYOND 
the end. Thus, if "SOURCE: §0A00 i2A5*' is indicated, the a 

SAVE will save the area $7A00 to $L2A4 inclusive. 

NOTE: the command prompt "%comes up after a Gatalog. 

Execute any disk commands with the X command. 
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THE EDITOR 


I III. I IM lUK 


inuih ally Llitite ave three modes ia the editor; the COMtUND 
iiitnh^, i hr ADD oT INSERT mode, and the EDIT mode- The main 
s>ir‘ hi tlir COMMAND mode, which has a '’colon" (:) as prompt- 


I liMtinKiiul Mode 

Him many of the COMMAND mode commandsp only the first letter 
ul the comniand is required, the rest being optional* This 
siiainml, shows the required command characters in upper case 
anil the optional ones In lower case. In some commands, you 
Limsi specify a line number, a range of line numbers, or a 
range list, A line number is just a number, A range is a 
|iaU of line numbers separated by a comma* A range list 
4'(iiislsts of several ranges separated by slashes (*V")* 

Sevcjral commands allow specification of a string. The string 
Lillist be "delimited" by a non-numeric character other than the 
alusli. Such a delimited string is called a d-string. The 
usual delimiter is single or double quote marks or ") . 

f-lne numbers In the editor are provided automatically. You 
never type them when entering text; only when giving com" 
mands. If a line number In a range exceeds the number of the 
last line, it is automatically adjusted to the last line 
tmmber. The commands are: 


IJ Lmcm: 

HI: (address) 

HI mem: sets Che upper limit fcr the source file and 
beginning address for the OBJ file. 

NKW 

[h! Ictus present source file, resets HIMEN to $800^ 
uud starts fresh- 
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PORT 

PORT (2,4 , or 5) 

Selects a printer in specified port for output, but dons 
not format output as does the PRTR command. 


USER 


This does a JSR to the routine whose address is In 
$32E,$32F. This vector is reset to Its default (kernel) 
value when either an Exit to BASIC or an EXECUTIVE modn 
command G (run a program) is done. If this is the case, 
you may use the USER command to send you to the EXEC 
mode. You can reconnect the SUPPLIED USER routines 
{CKRGEU 80, XREF, XREF-XL) by doing an A^0G from tlie 
monitor. This avoids having to rerun these utilities. 


TABS 

TABS <nurober><, nuraberX, *.*> <''tab character“> 

This sets the tabs for the editor, and has no effect on 
the assembler listing. Up to nine tabs are possible* 
The default tab character is a space, but any may he 
specified. The assembler regards the space as the only 
acceptable tab character for the separation of labels, 
opcodes, and operands* If you don't specify the tab 
character, then the last one used remains* Entering TABS 
and a RETURN will set all tabs to zero* 


LENgth 


This gives the length In bytes of the source file, anti 
the number of bytes remaining before MERLIN'S UIMKM 
(usually $8000 - not BASIC UIMEM), 



lU in I dm' I ti M.iniiJi 1 


THE EDITOR 


U1 ir I r 


\i\n' II' ( t I i\v. number) 


Tdifi prUiLs In hex the 
I hr Jipecif led line» 
liuMlt.oii of the end of 


location in raeoiory of the start of 
"Where 0" (or "W0") will give the 
source * 


IIUN I ror 

Tlile exits to the monitor* You may re-enter by "Q" 
RETUKN- This re-establishes the important sero page 
|Ki inters from a save area inside MERLIN itself- "Q" 
UETliUN will give a correct entry, even if you have messed 
up tlie zero page pointers while in the monitor* This 
facility is designed for experienced programmers, and is 
not recorumended to beginners- 

You may re-enter the editor directly with an "R" RETURN 
command. This re-entry, unlike the others, will use the 
zero page pointers at $0C - $11 instead of the ones saved 
upon exit. Therefore, you must be sure that they have 
not been altered- For normal usage, however, "Q” RETURtI 
should be used to re-enter HERLIN- 


TRuncON 

This sets a flag which, during LIST or PRINT, will termi¬ 
nate printing of a line upon finding a space followed by 
a seraicoloa. It makes reading of source files easier on 
the Commodore 40 column screen. In the assembler, whan 
used as*a. pseudo-op, limits printing of the object code 
to three bytes per line and has no effect on comments. 
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Tine i ;!)! I nit 


TRuiicOFf 

This returns to the default condition of the trijiuiatlnn 
flag (which also happens au Co?na tically upon entry to i hi¬ 
ed i tor froni the EXEC mode or froQi the assembler). Al I 
source lines when listed or printed will appear nornia 1 , 


Quit 


Exits to EXEC mode. 


ASH 


This passes control to the assembler, which attempts to 
assemble the source file, Firstj however, you are askcrl 
If you wish to "update the source". This is to remind 
you to change the date or identification number in your 
source file. If you answer then the assembly will 
proceed* If you answer Y , you will be presented with 
the first line in the source containing a *V" and are 
placed in EDIT mode* When you finish editing this line 
and hit RETURN, assembly will begin* If you use the STOP 
edit abort command, however, you will return to tlie 
EDITOR command mode, and any l/O hooks you have estab¬ 
lished, by PORT or PRTRetc*, will have been discon¬ 
nected, This will also happen if there is no line with a 


Function key FI 

During the second pass of assembly, typing an FI will 
toggle the list flag, so that listing will either stop 
or resume. This will be defeated if a LST opcode occurs 
in the source, but another FI will reinstate It, 
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THE EDITOR 


( >(' I i> I I* 

l>t ( 1 I IK* luiiuber) <range> <range iist> 

iJi- O' I r ( I inirj; e ) 

Hill’ll' ( t iingt* List) 

Thin ileleteij the specified lines, Since^ unlike BASIC, 
till' line numbers are fictitious they change with any 
JiiniitLloii or deletion. Therefore, you MUST specify the 
liLglu!r rnriige first for the correct lines to be deleted t 


lO'ji J (ice 


Uc'pince (line number) 

10'pi nee (range) 

This deletes the line number or range, then places you 
IIIto INSERT mode at that location. 


\.iti l 


I, liJ L 

hint (Line nuEnber) 
l.lftt (range) 

List (range list) 

1. Ists the source file with added line numbers. Control 
characters in source ate shown in inverse, unless the 
listing is being sent to a printer or other non-standard 
outport. 


The listing can be aborted by STOP or with '7" key. You 
uiay atop‘Che listing by hitting the space bar and then 
advance a line at a time by hitting the space bar again. 
Any cjther key will restart it. This space bar pause also 
wtirlui during assembly and the symbol table print out. 
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J ill. KIM IIHI 


- (period) 


L. 1 SCS starting from tlia beginning of the last ... 

h”" type L10,f00 then linen 10 

100 .ill be Listed. If yon then ose lifting olM 

start again at 10 and continne until stopped (the end ol 
cne range is not remembered). 


/ 

/ <1106 number> 


inis oontinnes listing from the last line number listed 
or, when^ a line number is specified, from that line! 
This listing continues to the end of the file or niitll ti 
is stopped as in LIST. 


Print 

Print 

Print (line number) 

Print (range) 

Print {range list) 

chat line numbers an 


PRinTeR 


PRinTeR (command) 


This command is for sending a listing to a printer 
page headers and provision for page boundary skips, 
default parameters may be set up by changing the 
line In the BASIC MERLIN program. The syntax of this 


w I I b 
I'hf' 
IM I A 

I ft : 


PRTR PORT (string) <page header> 

If the poet number Is not 2, or 5, then output 
to the video screen- 


In fit'IN 
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Il'iiM 'I f’l.mihi ] 


niK t-DITOH 


M Mir jM^i^ lieatit:r is onsicted^ the header will consist of 
until tiers only* 

nil': I NITI Ar.lXlATlON STRIi^G may not m omitted* if your 
|u J u( (;i: does not use a special string, use a null string 
Por example, if the printer is in Port 2 and does 
III if need an initialization string, PRTR 2 would be the 
roirect syntax* Cooimodore 1525 uses a null string, while 
is the inicHizacion string for IDS printers* 

iTMk ^ (no strings required here) will send output to the 
screen and allow you to see where the page breaks occur. 
No output is sent to the printer until a LIST, PRINT, or 
ASM command is issued. 


V 1 nd 

IM iid (d"String) 

Kind (line number) <d-scring> 

IM nd (range) <d^string> 

Find (range list) <d-string> 

This lists those lines containing the specified string. 
It may be aborted with STOP or *'/" key. Since the F7 
case toggle works in command mode, you can use it to find 
or cliange strings wath lower case characters* 


(hniiige 

Ghinge {d-string d-string) 

Ktiaiijje (line number) <d-string d-'string> 

Kh-mge (range)'<d-string d-string> 

Khungu (range list) <d-string d-string> 

Tills changes occurrences of the first d-string to the 
ficcond d-string. The d-string must have the same de*- 
IhtilLur with the adjoining ones coalescing* For example, 
(u I h.iiigc' occur ranees of "speling" to "spelling " through- 
inii ! Ivc range 20,100, you would type C20,100 
iipi'I I iig"spo 1 I ing*', If no range is specified, the entire 
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source file is used. 

Before ttse change operation begins, you are asked whethm 
you want to change or '^some" . If you select ‘'soiuu'* 
by hitting tlie S key, the editor stops whenever Lin* 
first string Is found and displays the Hoe as It woulfl 
appear with the change- If you then hit ESCAPE or auy 
control character, the change displayed will not be miide* 
Any other key, such as the space bar, will accept the 
change. STOP or V key will abort the change process. 


COPY 

COPY (line number) TO (line number) 

COPY (range) TO (line number) 

This copies the line number or range to just ^below'" 
(numerically) the specified number. It does not delete 
anything. 


HOVE 

HOVE (line number) TO (Line number) 

MOVE (range) TO (line number) 

This is the same as COPY but after copying, automatically 
deletes the original range. You always end up with elm 
same lines as before, but in a different order. 
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rut: liDLTOK 


l.l \ I 

\ 4[t 

I 4 M I 4 - I f iutj) 

14 I I ( 1 i uo luimber) <d-striag> 

I4M <d“string> 

i.-in (inUige list) <d“stiting> 

iliiii pieseots each line of the line number, rang a ^ or 
lunge list line by line to be edited and puts you into 
Lhe EDIT mode. If a d-strlng is appended, only those 
lines containing the d-string are presented. See the 
discussion later in this chapter concerning the EDIT mode 
coiEiiiiands . 


licx-^IJcc Conversion 

If, in the commaod mode, you type a decimal number 
(positive or negative) the hex equivalent is returned. 
If you type a hex number, prefixed by the decimal 
equivalent is returned. All commands accept hex numbers, 
which is mainly convenient for the HImem: and $YH com- 
matids, 


TEXT 


This converts ALL spaces in a source file to inverse 
spaces. The purpose is for use on "text" files so that 
it is not necessary to remember to ^ero the tabs before 
printing such a file. This conversion has no effect on 
anything except the editor^s tabulation. 
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FIX 


This undoes the effect 
technical housekeeping 
the command FIX be 
sourcesj after which 


of TEXT, It also does a nuinher n| 
chores« It is recommended t h;U 
used on all files from oxtenml 
the file should be saved» 


NOTE: the TEXT and FIX routines are written In SWEET th 
and are somewhat slow. Several minutes may be needed for 
their execution on large files. FIX or an EDIT will 
truncate any lines longer than 255 characters. 


SYM 

SYM (address) 

MERLIN normally places the symbol table in the RAM behimt 
the KERNAL ROM C5E000-$FD00). This space is qnite ade¬ 
quate for all but gigantic programs. In case this space 
is used up, the SYH cominand gives you a means to direct 
the assembler to continue the symbol table In anotlier 
area. If you type SYH $9000, for example, and assemble 
the program, when and if the symbol table uses up its 
normal space, it will be continued at $9000 until it 
reaches BASIC HIHEM. It must be noted that the SYM com¬ 
mand will be cancelled by a HIMEM command or by exit to 
EXEC mode and re-entry (set HIIEM before setting up a SYM 
address). 

The SYM address must be above HIMEM and below BARIC 
KIMEH. If the symbol table grows beyond the allotted 
space, you will get a memory error during the first pans 
of assembly, 
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IhJ'- I i>ainuHu! i.oj'/jles the 80 coiumn motley provided a Data 
Vldri.i>iik 80 cartridge is installed* Note that the 80 
Eiiude uses up 4K of source space ($9000 - $9FEF) * 

ln( h>[iK sources it may be aecessary to ase the 80 column 
iiiiidr only foe editing and then switch to the 40 column 
modr for assembly* This is possible since switching to 
i\\i- 40 column mode automatically retreives the 4K of 

aparo* Note also that MERLIN does NOT support the 
V i ileopak 80 40 colunin mode- For technical reasons j the 

Vil) cotiHuand sends you back to the EXEC mode after the 
f!w I I ch. 


TW ( K f lid Word ) 


i'W (d string) 

I' W (tin e n uin be r ) < d- s t r i ng^ 
IW (range) <d^string> 

IT/ (range list) <d-string> 


This is an alternative to the FIND command* It will find 
the specified word only if it is surrounded, in source, 
by non-alphanumerlc characters* Therefore, FW’CAT" will 
find: 


CAT 

CAT-1 

CCAT,X) 

but wili not find CATALOG or SCAT* 


CU (Cliaiige word) 

i:w (d-striug d-string) 

CW (line number) Cd-string d“SCring> 

CW (raiigii) <d-string d^string> 

HW (Iangn list) <d’string d-string> 

Thin works similar to the CHANGE command with the added 
IrutMtiui an duscribnd under FW * 
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EW (Edit word) 

EW (d-scrlng) 

EW (line number) <d-striiig> 

EW (range) <d-strlng> 

EW (range list) <d“strlng> 

This is to EDIT as EW is to FIND. 

NOTE ON DELIMITED STRINGS: For the commands involving (le™* 

limited strings <a d-string), the character acts ’as a 

wild card. Therefore, F"Jon~s" will find both "Jones" and 
"Jonas**. 

VAL 


VAL "expression" 

This will return the value of the expression as the 
assembler would compute It. 

Examples: 


VAL "LABEL" 


V^X "$1000/2" 
VAL "Z1000‘* 
VAL ! "a"-"0"I 


gives the address (or value) 
of LABEL for the last assem¬ 
bly done or "unknown label" 
if not found* 
returns $0S00 
returns $0008 
returns $0011 





Ml Hi IN iJh^M II ill.11 


Tiil^ 1£ DITCH 


1,1C II 


I'll In r i;inl!s the ercoc channel on the current disk drive 
iuul tii iiilji out the error Inforraatioa* This should be used 
il !ji>iiur disk operation makes the drive light blink but 
diJir.'i lint, [iroduce an error message. There are certain disk 
uiiurs that the operating systems does not signal back to 
I hr calling program- This provides a means for checking 
I hriiK 


Add/Insert Mode 


rhi‘ ADI) and IDJSERT modes in the editor act as if you are in 
i Ur edit mode, except that CTRL-R will do nothing, and the 
ttjcl t from ADD mode acts as described^ Hitting RETURN, for 
rxuiiipJu, will accept the entire line as shown on the screen. 


aiid 


This places you in the ADD mode- You may enter lower case 
text (useful for comments if you have a lower case adap¬ 
ter) by hitting F7. This acts as a case toggle, so 
another F7 returns you to UPPERCASE mode. The shift key 
inverts the current case. Shift lock should not 
ordinarily need to be used- To exit from ADD mode, hit 
RETURN as the FIRST character of a line. You may also 
exit the ADD mode by CTRL-X or STOP which also cancels 
tlie current line - 

You may enter an EMPTY line by typing a space and then 
RETURN. This will not enter the space into text, it only 
bypasses the exit. The editor automatically removes 
extra spaces at the end of lines. 


35 


MERLIN Users Manual 


TflE EDI KIR 


Insert 

Insert <iiTie number> 

This allows you to enter text just below (numerically) 
the specified line. Otherwise^ it functions the same ns 
ADD command (above)* 


Function key F7 (or Control-L) 

Toggles the current case. If you are In upper case, F7 
will place you In lower, and vice versa. Upper case Is 
defaulted to when entering each new line- 

To change the case of a word, type F7, then copy over the 
word using the right hand cursor control key. 


Edit Mode 

After typing E in the editor, you are placed In EDIT mode. 
The first line of the range you have specified is placed on 
the screen with the cursor on its first character. The lino 
Is tabbed as It Is in listing, and the cursor will jump 
across the tabs as you move it with the arrow keys. When you 
are through editing, hit RETURN. The line will be accepted 
as It appears on the screen, no matter where the cursor is 
when you hit RETURN. 

The cursor keys do not work as their markings suggest In edit 
mode. The up/down arrow key works as a Jtove cursor left key 
and the left/right arrow key works as a move cursor right 
key, 
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I mil ill I I ui Lilt; Insect Key (insect) 

IHjsins Insertion of characters. This is Cenninated by 
nny rnntrol character except the CTRL-L case toggle, such 
I'is I he arrows or RETLIRN. 


Hunt Mi i-IJ (delete) 

Deletes the character under the cursor* It can also be 
referred to as a backwards delete* 


Hontiol-K (find) 

llnds the next occurence of the character typed after the 
CrRL“F* This is recursive* 


ContL’ul”0 (insert special) 

Emvetions as CTRL^I, except it inserts any control char¬ 
acter (Including the command characters such as CTRL-A). 

(do s) 

it entered as the first character of a line gives 32 
it entered as any other character of the line, gives 3^S 
spaces bordered by *'s. 

htiip Key (cancel) 


Alxuts HDiT mode and returns to the editor's command 
iimi.I.m tile current line being edited will retain its 
i>i i g i i;a ! form * 
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Coatrol-fl (go to line begin) 

Place.^ the cursor at the beginning of the line, 

Control-N (go to line end) 

Places the cursor one space past the end of the line. 
Control-R (restore line) 

Returns the line to Its original form* (Not available In 
ADD and INSERT modes.) 


Gontrol-A (delete line right) 

Deletes the part of the line following the cursor and 
terminates editing* 


Return (RETURN key) 

Accepts the line as It appears on the screen and fetches 
the next line to be edited, or goes to the command mode 
if the specified range has been completed. 

The editor automatically replaces spaces in connnents au(! 
ASCII strings with Inverse spaces. When listing, it 
converts them back, so you never notice this. Its pur¬ 
pose Is to avoid Inappropriate tabbing of comments and 
ASCII strings. 
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Im I Ur i.ifiir (j 1 AiiOl I strings j this is only done when the 
Nr I lull Mir is a quote (”) or a single quote C^)* can, 

howi'Vrr, accomplish the same thing by editing the linej 
irpl.if Ing the first delimiter with a quote^ hitting 
iOiltIHNj then editing again and changing the delimiter 
hui k in thr^ desired one. 

Ill i\ Line such as LDA ^ you can prevent the extra 

laUliing by entering the line with a space before the 
I I I i'll quote (LDA // , then typing control^N and then 

using the cursor control to delete the extra space. 
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i ill AMil.HhI.I'.K 


Hct I luu of the documentation will not attempt to teach 
ymi jlfMki'iiibl y language. It will only explain the syntax you 
;iir to use In your source files, and document the 

IhNMiiiiMi that are avaliable to you in the assetsbler^ 


MuinlifM Format 


rhi‘ assuinhler accepts 
lUMiiiM leal data. Hex 
hi II.a y numbers by 
a I i‘ .11 I equivalent; 


decimal, hexadecimal, and binary 
numbers must be preceded by and 

thus the following four instructions 


J.hA iflW LDA #$64 IDA ^%11|30100 


LDA tf%0U00100 


Ari Indicated, leading ^eros are ignored* The *'#” here stands 
tor "nuiEiber" or ‘'data", and the effect of these instructions 
i'i t o Load the accumulator with the number (decimal) 100. 


A number not preceded by is interpreted as an address^ 
I'he t el u re : 


l.l>A 1000 LDA $3E3 LDA %1111101000 

an* o(juivaient ways of loading the accumulator with the byte 
Uiat resides in tnemory location $3E8* 


41 



Hi'IULtlJ User's Miiimal 


TIIK ASSUMIILER 


Use the iHimbcr format that is appropriate for 
example, the data table; 


clarity. For 


DA $1 
DA SA 

DA $6<'4 

da $3E8 

DA $2710 

Is a good deal more mysterious that Its decimal equivalent; 

DA 1 

DA 10 

DA 100 

DA 1000 

DA 10000 


Source Code Format 


A line of source code typically looks like: 

LABEL DPCODZ OPERAND ;COMMEHT 

A line containing only a comment must begin with rnm- 

aent lines starting with are accepted and tabbed to the 
comment Eteid. The assembler will accept an empty line in 
the source code and wiU treat it Just as a SKP 1 iLtruction 

lai be printed!" '^^™ber 

The number of spaces separating the fields Is not important 
except for the editor's listing, which expects Just one 

The maximum allowable LABEL length is 13 characters, but more 

bl!n tM assembly listings. A label must 

begin with a character at least as Urge, In ASCII value, as 

v,t contain any characters less, In ASCII 

value^ Lh£in the riumber zero^ 


til lu t li i M I 
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A li(M- iih.4/ ( lull *i ill a label by itself. This is eqaivaleat to 
♦ ■r|M M III); I ln‘ laboL to the current value of the address 

4 111 i 111 I»t . 

lln^ anui-mliliM examines only the first 3 characters of the 
iiritplil.. Fi>i exaiinjle, you can use PAGE instead of PAG. The 
ariru’MibliM listing will truncate the opcode to seven letters 
a ml will iiE>( look well with one longer than four unless there 
I tji III! iipuraiiilK 

I hr ijhix I iiiinii allowable combined OPERAND + COMMEMT length is 64 
t hn 1 nr i i!L'a . You will get an error if you use more than this* 
A i'oiiuin.'iiL line by itself is also limited to 64 characters. 


I:H|iI rss Lous 

Vt> (II,ike clear the syntax accepted and/or required by the 
4i!i:iiMiitilerj we must define what is meant by an "expression"* 
ICHiu’ussious are built up from "primitive expressions" by use 
oi atlthiiiutic and logical operations* The primitive expres- 
tiiiHia are: 


1. A label. 

2, A number (either decimal^ $hex, or %binary)- 

1. Any ASCII character preceded or enclosed by quotes or 
single quotes. 

^ 1 . Tlie character * (standing for the present address)* 

AM iiuiiiber formats accept 16-bit data and leading zeros are 
n(^V(?r required. In case 3, the "value" of the prlenitive 
cKpiusslon is just the ASCII value of the character in 
f](jiuiJunlore U/L case format* The high-bit will be on if a 
(|uijM' (") is used, and off if a single quote (') is used* 

I'Im’ assembler supports the four arithmetic operations: +, —, 
/ (I tu t'ger division) j and * (multiplication). It also sup'^ 
|nM E'I I lie three logical operations: I (Exclusive OR), • (OR), 
uii.l (AMD). 
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Some examples of legal expressions are: 


LABELl-LABELZ 
2*LABEL+$23l 
U3 WA^lli 

"0"aABEL 

LABELS$7F 

*-2 

LABEL.3^1004^0000 


(LABEL2 minus LABEL!) 

(2 times LABEL plus hex 231) 

(123A plus binary 10111) 

(ASCII K minus ASCII "A* plus 1) 
(ASCII "0" LOR LABEL) 

{LABEL AND hex 7P) 

(present address minus 2) 

(LABEL QR binary 10000000) 


Parentheses have another meaning and are not allowed In 
expressions. All arithmetic and logical operations are done 
from left to right (2+3*5 would assemble as 25 and not 17), 


ImEnedlate Data 


For those opcodes such as LDA, CMP, etc., which accept Im¬ 
mediate data (numbers as opposed to addresses) the immediate 
mode IS signalled by preceding the expression with "11". An 
example is LDX #3. In addition: 


//<expression 
i?>expression 
^^express ion 

ff / expres s ion 


produces the low byte of the expression 
produces the high byte of the expression 
also gives the low byte (the 6510 does 
not accept 2-byte DATA) 

Is optional syntax for the high byte 
of the expression 


The ability of the assembler to evaluate expressions such as 
LAR2~LABl-l is very useful for the following type of coder 


COMPARE 

LDX 

#EODATA”DATA-l 

LOOP 

CMP 

DATA,X 


BEQ 

FOUWD ;found 


DEX 



BPL 

LOOP 


JMP 

REJECT ;not found 

DATA 

HEX 

E3BC3490 

EODATA 

EQLT 
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Uiili I y|M! uL code ^ you can add or delate some of the 

(lAlA hHuI t tir value which is loaded into the K indcK for the 
t I HI 1 [Ki t I la n L will be automatically adjusted. 


Ad.lI i*M'i i Miidus (for 651{3 Opcodes) 

1 lu' .ifsniMuli 1 or accepts all the 6502 opcodes with standard 
iiiiii’im HI I c ?i - It also accepts BLT (branch if less than) and BGE 
(luamh II greater or equal) as synonymous to BCC and BC3. 

I lifM are 12 addressing modes on the 6510. The appropriate 
fllilthlM aynuaK; for these are: 



Syntax 


Example 

1 III jl 1 [ ud 

OPCODE 


CLC 


Arriimij;la tor 

OPCODE 


ROR 


hiuin'iiiate (data) 

OPCODE iS^expr 

ADC 

tfSFS 


- 


CUP 

if "M" 




LDX 

#>LABELl-LABEL2-l 

/iM'o page (address) 

OPCODE 

expr 

ROL 

6 

Indexed X 

OPCODE 

expr,X 

LDA 

$E0,X 

tndexed Y 

OPCODE 

expr jY 

STX 

LAB.Y 

Aluiolute (address) 

OPCODE 

expr 

BIT 

$300 

Indexed X 

OPCODE 

expr,X 

STA 

$‘H000,X 

tndexed Y 

OPCODE 

expr,y 

SBC 

LABEL-l,Y 

1 n d 1 n.! c c 

JMP (expr) 

JMF 

($3t'2) 

Pre indexed X 

OPCODE 

(expt,X) 

LDA 

C6,X) 

Postindexed Y 

OPCODE 

(expr).Y 

STA 

($fe:),v 


MOTK: There is no difference in syntax for zero page and 

iduiohitu modes- The assembler automatically uses zero page 
iiiudi- whiMi appropriate* MERLI^T provides the ability to FORCE 
Mini /i'lu page addressing. The way to do this is to add 
aiiyililiig to the end of the opcode. Example: 

i.hA $10 assembles as zero page (2 bytes) while, 
l.bA; $10 assembles as non-zero page (3 bytes). 

AI nil, hi r Ii(‘ Indexed indirect modes, only a zero page ex pres— 
nIoh In aMuwcnl, and the assembler will give an error message 
n till’ '*i*ipt** lIch's t^ot evaluate to a zero page address. 
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NOTE: 
letter 
ari "a" 


Tlse '■accuiULilator mode'' does not require an 
"A"). Some assemblers perversely require 
in the operand for this mode* 


operand 
you to 


{ the 
put 


The assembler decide the legality of the addressing 

lor any given opcode. ^ 


mode 


Pseudo Opcodes - Directives 


( = ) (EQUate) 

Label expression 

Label = expression (alternate syntax) 

Used to define the value of a LABEL, usually an exterior 
address or an often used constant for which a meaningful 
name Is desired. it is recommended that these all be 
located at the beginning of the program. The assembler 
will not permrt an "equate" to a zero page number after 
e label equated has been used, since bad code could 
result from such a situation (also see "Variables"). 


ORG (set ORlGin) 
ORG expression 


Establishes the address at which the program is designed 

to the present value of ItlMFiM; 
($8000 by default). Ordinarily there will be only one 
ORG and it will be at the start of the program. If more 
than one ORG is used, the first one establishes the LOAII 
address. This can be used to create an object file tliiir 
would load to one address though it may be de.slpned to 
run at another address. 


You cannot use ORG *-l to back up the object po In tor a un 

is done in some assemblers. This must be done I unload 
by DS , 
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I'lM (I'll I .1 (rxt I Lit! in asseEiibly) 

I' I M I I h ' I L 11 I II E' 

I'lJ l M I iMiH-iuie" , (drive parameter accepted in standard 
nV'ilak) Lends the aaraed file and "inserts" it at the lo-' 
« »H hill til die opcode > 

iKnid '’Insert" refers to the effect on assembly of the 
hnjitiun of the source. The file itself is actually 
((Inri'd just following the main source. Text files are 
»(’<|iitt’ud by this facility in order to insure memory 
|iMiltjcLlou, A memory error will occur if a PUT file 
giit'S beyoud UlflEH: » These files are in uemory only one 
i%t a timCj SO a very large program can be assembled 
irdiig the PUT facility, 

llii'fu are two restrictions on a PUT file, firsts there 
(nimuJt be MACRO definitions inside a. PUT file, they must 
hr III the main source. Second, a PUT file may not call 
a rial: her PUT file with the PUT opcode* Of course, link¬ 
ing can be simulated by having the "main program" jost 
contain the macro definitions and call, in turn, all the 
burs with the PUT opcode. 

Aliy variables (such as ]LABEL) may be used as "local” 
variables. The usual local variables ]I through ]8 may 
be sl:L up for this purpose using the VAR opcode, 

Ttn‘ PUT facility provides a simple way to incorporate 
uuh h used subroutines, such as PRINT or PRDEC, in a 
pi agrain. 


VAR (setup Vv\Riabies) 

VAH CMpr;uKpr;expr,., 

IhI a Is just a convenient way to equate the variables ]1 
dll H fid "VAH T;$ 42 ;LAaEL" will set jl = 3 , j 2 $ 42 , 

.. ] ^ ^ LAllEU,. This is designed for use just prior to 

PUi II a RUl file uses ]i - ] 8 , except in >>> lines 
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for calling macros, there MUST be a previous declaration 
of these, 


SAV (SAVe object code) 

SAV filename 

SAVE filename", (drive parameter accepted) will save 
the current object code under the specified name. This 
acts exactly as does the EXEC mode object saving 
command, but it can be done several times during 
assembly, 

This pseudo-opcode provides a means of saving portions 
of a program having more than one OEG. It also enables 
the assembly of extremely large files. After a save, 
the object address is reset. 

The SAVE command sets the address of the saved file to 
Its correct value. For example. If your program 
contains three SAV commands, then it will be saved in 
three pieces, Uhen LOADed later with the LOAD '"FILE", 
8,1 syntax, they will go to the correct locations, the 
third following the second and that following the first. 

Together, the PUT and SAV opcodes make tt possible to 
assemble extremely large files. 


DSK (assemble directly to DISK) 

DSK filename 

OSK filename" will direct the assembler to assemble the 
following code directly to disk. If DSK Is already In 
effect, the old file will be closed and the new one 
begun. This is useful primarily for extremely large 
files. 
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I tin ( I "JM nl '.mil t’lLif) 

I nil 

Mil * i*(ii’ly usiid or needed pseudo opcode Instructs the 
ii - M mb I It r Lo Ignore the rest of the source. Labels 
iM rm I I nji uliter EHO will not be recognieed. 

IMIM ( bl iMiii y section) 

bIJH 

This starts a section of code that will be examined for 
vuliie of labels but will produce no object code. The 
*‘Xpiussion must give the desired ORG of this section. 
It is possible to re^ORG such a section using another 
nriMHY opcode or using ORG. It is legal to use DS op- 
todes in dummy sections but^ since the address is not 
ptintud for a DS opcode^ it is preferable to use other 
lurms (DA, DFB, etc)* Note that, although no object code 
Is produced from a dummy sectioUp the text output of the 
u.sruniibLer will appeat as if code is being produced. 

bKNN ([luicitiiy EMO) 


Id Mb 


rhh; eiuls a duEiimy section and re-establishes the ORG 
uililiess to Che value it had upon entry to the dummy 
IIri’ t iu n . 
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Forma11ing 


LSI ON/OFF (LlSTing control) 

LSI ON or OFF 

This controls whether the assembly listing is to be sent 
to the screen (or other output device) or not. You may, 
for examplej use this to send only a portion of the 
assembly listing to your printer. Any number of LST 
instructions may be In the source. If the LST condition 
is OFF at the end of assembly, then the symbol table 
will not be printed. 

The assembler actually only checks the third character 
of the operand to see whether or not it Is a space. 
Therefore, LST FRED will have the same effect as LST 
OFF. The LST directive will have no effect on the 
actual generation of object code. If the LST condition 
Is OFF, the object code will be generated much faster, 
but this is recommended only for debugged programs. 

NOTE: Function key FI from the keyboard toggles this 

flag during the second pass. 


EXP ON/OFF (macro EXPand control) 

EXP ON or OFF 

EXP ON will print an entire macro during the assembly. 
The OFF condition will print only the »> pseudo-op. EXP 
defaults to ON. This has no effect on the object coded 
generated. 
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IMII I 


rAII 


Dll I hi; .‘it’coi’td p^ss Eihis causes assembly to pause until 
;( ki'V Is hit- This can also be done from the keyboard 
hy h 1 1 iJ iig the space bar. 


PAM (iu‘w PACe) 


PAi. 


This sends a formfeed ($0C) to the printer. It has no 
ri feet on Che screen listing even when using an 60’- 
cuhiiun cartridge i Note that the Commodore 1525 printer 
dous not recognize a form feed. If PETR is in effect, 
however, this character will be intercepted and acted 
upon [properly* 


Ah I (send a Line of ASIerisks) 

AST expression 

This sends a number of asterisks (*) to Che listing 
e(|uai to the value of the expression. The number format 
is Lhu usual c'^e, so chat AST 10 will send (decimal) 10 
asterisks, for example. The number is treated modulo 256 
witli 0 being 256 asterisks! 


IlKi (SKIP Lines) 
hKI' expression 

I'lMs sends "expression" number of carriage returns to 
the listing. The number format is the same as in AST. 
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TR ON/OFF (TRuiicare control) 
TR ON or OFF 


TR ON 
source 
TR OFF 


lldiltc object code printout to three bytes per 
line, even If the line generates more than tliree. 
resets It to print all the object bytes. 


S t r 1 ng s 


The opcodes In 
the string, 
acceptable : 


this section also accept hex data after 
Any of the following syntaxes are 


ASC "strlng'’878D00 
ASC "string",878D00 
ASC "strlng“ j87,8D,00 


TXT (define TeXT) 


TXT d-strlng 


This puts a delimited Commodore ASCII string Into the 
object code. The only restriction on the delimiter Is 
that It does not occur In the string Itself. Different 
eliraiters have different effects. Any delimiter less 
than (In ASCII code) the single quote (') will produce a 
high-bits on, otherwise the hlgh-blts 
will be off. For example, the delimiters !"?$!& will 
""^e^tlve" ASCII, and the delimiters 
produce one In "positive" ASCII. Usually the 
quote ( ) and single quote {") are the delimiters of 
c oice but other delimiters provide the means of 

nserting a string containing the quote or single quote 
as part of the string- 
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'I I (ni‘x(tal Ch.'itacLer Inverted) 

IM I i\ ^ M b IIK 

III In hi ihc same as TXT except that the string Is put 
Inin ijuMiuu y with the last character having the opposite 
hl^h hit as the others- All choices for delicniters 
ni Inn wise have the same effect as TXT. 


(tUhtiie ASCII text) 

A.SC il !. Li 1 iig 

I hi a is the same as TXT except that It uses standard 
Ard:iL annotation. 

AS I {(toN ile AScil Inverted text) 

AM (! u r r ing 

lilts is the same as A3C except that the string is put 
iiiio memory with the last character having the opposite 
higli bit to the others. ASI is to ASG as DCI is to TXT. 

Hl' V (tie I i (VC REVerse text) 


I'll I it puts the d-string In memory backwards. Example: 

Kl'iv "RACECAR" gives "RACECAR" 

(iiiHiyhu L’hac wasn't such a good example) 

RLV "CCHMODORE" gives "ERODOHHOC" 

hi-find I er choices are the same as with TXT. HEX data 
I (itmni l)u added after the string terminator. 
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SIR (define text with length byte for STRlngs) 
STR d'-string 

This is the same as 
preceding the string- 
after the string only^ 
any hex bytes. 

In summary: 


Assembles as (hex) 

61 42 43 
61 42 C3 
43 42 61 
41 62 63 
41 62 EJ 


Data and Allocation 


DA (Define Address) 

DA expression 

This stores Che tuo-byce value of the operand, uiiually 
an address, in che object code, lou^byte first. For 
example, DA SFDF0 will generate FS) FD. Also accepts 
multiple data (e.g. DA 1,10,1(S0) 


Command Input 


TXT 

'Abe 

DCI 

'Abe 

REV 

'Abe 

ASC 

'Abe 

ASI 

'Abe' 


Annotation 

Cnanodore ASCII 
Commodore ASCII 
Commodore ASCII 
Standard ASCII 
Standard ASCII 


TXT but places a length byte 
The syntax will accept hex data 
but the length will not Include 


DDP (Define Double Byte) 

DD8 expression 

As above, but places higb-byte first. Also accepts 
multiple data (e.g. DDB 1,10,100). 
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IM 111 ( IU' M tH’ li y l uH ) 

hi II fi J4 |M ■' rn» I i:}il 

111 In Che bytes Specified by the operand into the 

i>h|r'4i tt>i3e. It accepts several bytes of data, which 
Muini 3 h! iiioparated by commas and contain no spaces« The 
rM,nMlard number format Is used and arithmetic is done as 

inniu t . 

Miu "//'■ symbol is acceptable but ignored, as is 
Tin* ">** symbol may be used to specify the high-byte of 
I lir label, otherwise the low^byte is always taken. The 
symbol should appear only as the first character of 
nil expression or immediately after if* That is, the 
i ii'i truc t ion DFB ^LABl—LAB2 will produce the high—byte of 
( lu^ Vrilue of LABl“LAB2 * 

I i>i exuiiipLe; 

Dl'B $34,100,LAB1-LAB2,%1011,>LABL-LAB2 

In .-i propeirly formacced DFB statement which will gen- 
♦M.itu the object code (hex): 

64 DE 0B 09 

■ I'isiimLiig that LABL = $81A2 and LAB2=$77C4, 


Ilii.K (dufLne HEX data) 
jri X ht'X-data 

IU hi is " an alternative to DFB which allows convenient 
liuik^rLlon of hex data. Unlike all other cases, the 
hi Liut reijfuired or accepted here. The operand should 
iniuilst of hex numbers having two hex digits (e.g, 0F, 

ii"i F)- ihey may be separated by commas or may be 
-td . An error message will be generated If the 

npiM.iiiit contains an odd number of digits or ends in a 
i niiimu, ur, as in all cases, contains more than 64 

I hil I 41 I 1’ t 4 . 
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DS {Define Storage) 

DS expression. 

This reserves space for storage data* It jeros out this 
space if the expression is positive, DS L0, for exam¬ 
ple, vill set aside L0 bytes for storage. Because DS 
adjusts the object code pointer, and Instruction like 
DS -1 can be used to back up the object and address 
pointers one byte. 
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i-Hit (ih l liM* from KeyBoarD) 

ifiUi ! KUM <il IJI I'1 

thtn ill lows a label to be equated from the keyboard 
dill iiqf assembly* Any expression may be input ted, 
ho hulliq^ expressions referencing previously defined 
lalnhiij liowever a BAD INPUT error will occur if the 
lufMii cannot be evaluated. If the operand is empty, then 
Hit' message '‘Give value fori followed by the the 

hilu’l, is printed on the screen. If the operand contains 
.1 tlth United string then this string is printed instead. 
S-'c MACRO LIBRARY and KEYMAC for examples of this* 

CUP {tjcgin a loop) 

CIM' expression (Loop) 

(end of LUP) 

lliii CUR pseudo-opcode Is used to repeat portions of 
iumree between the LUP and the “expression*' number 

ij| times. An example of the syntax for this is: 

J-UP 4 
ASL 


Wihi h uiil assemble as: 

ASL 

ASL 

ASL 

ASC 

and will show that way in the assembly listing^ with 
M^jiUiiiuci line numbers. 
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Perhaps the major use of 
an example: 


this Is for table building* 


As 


]A = 0 

LIJP $FF 
]A = ]A+1 

DFB JA 


vill assemble the table 1, 2, 3^ -.,$FF. 


The Qjaxtmym LUP 
simply be Ignored 


value is $304(^0 and the LUP opcode 
If you try to use more than this 


will 


CHK. Cpl^ce CKecKsum In object code) 


CHK 


This places a checksum byte Into object code at 
location of the CHK opcode (usually at the end of 
program)* 


the 
t h e 


ERR (force ERRor) 
ERR expression 


"ERR 

has 

will 


expression" will force an error if the expression 
a non zero value and the message BREAK IN LINE 
be printed. 


This may be 
for example 


used to ensure your program does not 
595FF by adding the final line: 


exceed ^ 


ERR *-l/$960(Zl 


lOTE: This would only alert you that the program 

long, and will not prevent writing above S9600 
assembly, but there can be no harm in this. The 
occurs only on the second pass of the assembly and 
not abort the assembly* 


Is to o 
flur [ rtg 
er ro r 
doi^s 
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THt: assembler 


AiiiH iiri av.i 1 I..11?le syntajc : 

j.lU< ( 5300 )- 54 C 

uhlili will inoduce aa error on the first pass and abort 
nnnruilMy tf location $300 does not contain the value 

'/iL, 


Ift.K {1ISi‘K itefiiiabLe opcode) 

II',It nprliiiial expressions 

Jhin Is a user definable pseudo opcode. It does a JSR 
ns. To set up your routine you should RUN it with the 
hXLL suode ”G*' coniEnand. Your routine can start at address 
V I with an RTS at that location, so that, effectively, 

I iir "(J” command simply loads the remainder of the 
pidj-r.im to $335. The following flags and entry points 


■ 1 ^ used by 

your routine: 

USUADS 


$335 

;Start of your routine 

PUTBYTE 

- 

$B726 


I'VAl, 


$B729 


PASSNUH 

= 

54 

;contains assembly pass number 

KKKCN’r 

= 

$1F 

;error count 

VMJIE 


$55,56 

;value returned by HVAL 

(M'NDLEN 


$23 

;contains combined length of 
;operand and comment 

NUi SMJUND 


$3D 

jsee discussion of EVAL 

WOKRSr 


$980 

■contains the operand and 
jcoraraent tn positive ASCII 


Vinn loiiliuc will be called by the USK opcode with A=0, 
V d oiul cjirry sec. To direct the assembler to put a 
hyfr lu t Iku object code, you should JSR PUT BYTE with the 
1 1 y I r ill A * 
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PUTBVTK will preserve Y but will scramble A and X- It 
returns with the zato flag clear (so that BME always 
branches)* On the first pass, PUTBYTE adjusts the 
object and address pointers, so that the contents of the 
registers ate not important. You MUST call PUTBYTE the 
SAME NUMBER OF TIMES on each pass or the pointers will 
not be kept correctly and the assembly of other parts of 
the program will be incorrectt 

If your routine needs to evaluate the operand, or part 
of it, you can do this by a JSR EVAL. The X register 
roust point to Che first character of the portion of the 
operand you wish to evaluate (put to evaluate the 
expression at the start of the operand). On return from 
EVAL, X will point to the character following the ev¬ 
aluated expression* The Y register will be 0, 1, or 2 
depending on whether this character is a right paren¬ 
thesis, a space or a comma* 

Any ocher character not allowed In an expression will 
cause assembly to abort with a BAD OPERAND error. If 
some label in the .expression is not recognized then 
location NOIFOUND will be non-zero. On the second pass, 
however, you will get an UNKNOWN LABEL error and the 
rest of your routine will be Ignored. On return from 
EVAl., the computed value of the expression will be in 
location VALUE and VALUE+l, lowbyte first. On the first 
pass this value will be insignificant if NOTFOUND is 
non“ze ro. 

Your routine may use zero page locations $60-$6F for 
scratch work but other zero page locations should not be 
altered. Upon return from your routine (RTS), the U3R 
line will be printed (on the second pass). 

When you use the U5R opcode in a source file, it Is wise 
to include some sort of check (in source) that the 
required routine is in memory. If, for example, your 
roiitine contains the byte 33 at location $340 then: 

ERR (3340)-$3 

will test that byte and abort assembly if it Is not 
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Hh IH ^hllM,nly, if you know that the required routine 
-IhhiI-I i'.m imIMh HXHict. l y two bytes of data, then you can 
(MMi(Mily) I hi'i k I or it by the following code: 

MAUI I. iWAl OPERA^’D 

nui >^“LABEL-2 

I h I'I u\]\ [nice ;\u error on the second pass if USR does 
u"i piMjhirH exactly two object bytes* 

It ('1 jinfr!?iVile to use USR for several different routines 
hi I Im* source. For example, your routine could 

ilu'if Mlh lirst: operand expression for an index to the 
ilrNliHtl routine and act accordingly* Thus "USR 1 , 
uli.iiiw!'i" vjonld branch to the first routine, "USR 
, ni 11 M " to the second, etc. 


I I Hid t t I oi |.l Is 


J)M (lilt tl I rue) 
[in i< s pI H I nn 


Tills, logother with ELSE and Fin are the conditional 
rwiisiilily PSl-iUDO-UPS. If the operand evaluates to EERO,. 
I Ill'll I hi^ assembler will stop generating object code 
(ittu M ft sees another conditional). Except for macro 
ii-itiiHs, ii will not recognise any labels in such an area 
ul i nilH. Jf the operand evaluates to a non^-zero number, 
iliHH assMiitbly will proceed as usual. This is very 
ir^fhiif Jui MACROS* 

[f Iu ls£i useful for sources designed to generate 
'hiy.liMy til ff I'rent code For different situations- For 
'’wiiii'l'l'h If yoii designing a program to go to on a 
IU>M ^ lil(i, yuii would want one version for the ROM, and 
umuluM , will) small differences to create a RAH version 
I III iIh bupj; i iq; piii jioses * 
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By Lisirig conditional assembly^ modification of such 
programs becomes much simpler, since you do not have to 
make the modification in two separate versions of the 
source code- Every DO should be terminated somewhere 
later by a FIN and each FIN should be preceded by a DO- 
An ELSE should occur only inside sucli a 1)0/FIN struc” 
ture< DO/FIN structures may be nested up to eight deep 
(possibly with some ELSE^s between). If D0 condition Is 
off (value 0), then assembly will not resume until Its 
corresponding FIN is encountered, or an ELSE at this 
level occurs- Nested DO/FIN structures are valuable for 
putting conditionals In MACROS- 


ELSE (ELSE do this) 
ELSE 


This inverts the assembly condition (ON becomes OFF and 
OFF becomes ON) for the last DO. 


IF (IF so then do) 

If char,)var (IF char is the first character of ]var) 

This checks to see if char is the leading character of 
the replacement string jvar.. Fosition Is important: 
the assembler checks the first and third characters of 
the operand for a match. If a match is found then the 
following code will be assembled- As with DO, this must 
be terminated with a FIN, with optional ELSEs be tween- 
The comma is not examined, so any character may be used 
there- For example, IF {=]1^ 

FIN (FlNxsh conditional) 

FIN 


This cancels 
with the next 
ON if Che FIN 


the last DO or IF and c out I tines assembly 
highest level of conditional assembly, or 
concluded the last (outer) DO or IF- 
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1 - fin |< I r 

III 

unvh 


* t .1 M 


nl [ lir U'V' of conditional assembly: 


MAt 

1J3A 

ii 


1A 

V * , 



[lAC 

Hi)V 

11:12 


1 ]' 

(,]1 

jSyntax MOVD (ADRl),Y;?22? 

1 MY 

1 1' 

{,12 

; MOVD (ADRl),Y;(ADR2),Y 

mv 

)i;]2 


ELSE 


; MOVD (ADRl),Y;ADR2 

i-m. 

]i:]2+i 


KIN 

Kl.SE 

IK 

(,!2 

;Syntax MOVD ????;CADR2).Y 

INY 

I F 

Ml 

; MOVD //ADRl; (ADR2) , Y 

NOV 

]1/$100;]? 


ELSE 


; MOVD ADR1;CADR2),Y 

MOV 

11+1;)2 


FIN 

ELSE 


;Syntax MOVD ????;ADR2 

1 1- 

1 

; MOVD //ADRl;ADR2 

MOV 

]1/$100;]2+1 


ELSE 


; MOVD ADR1;ADR2 

MOV 

]1+1;]2+1 


KIN 


;MUST close ALL 

FI N 


;condltionals, Count DOs 

FIN 


;& IPs, deduct FINs. Must 

«< 


;yield zero at end. 

nr.ixcs supported by 

MOVD; 

H(WI) 

ADRl;ADR2 


MOVI) 

(ADRl),Y;ADR2 


rHJVI) 

AI)Rl;(ADR2),Y 


M(3VM 

(A[)R1),Y;(ADR2) ,Y 

MOVI) 

//ADRl ; ADR2 


MOV 11 

//ADRl ; CADR2) ,Y 
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Macros 


MAC (begin HACro definition) 
label MAC 

This signals the start of a MACRO definition. It roast 
be labeled with the macro name* The name you use is 
then reserved and cannot be referenced by things other 
than the >>> pseudo-op (things like DA NAME will not be 
accepted if NAME is the label on MAC). See the section 
on MACROS for details of the usage of roacros. 


<<< (end of macro) 

<« 

This signals the end of the definition of a macro* It 
may he labeled and used for branches to the end of a 
macro, oroneof Its copies* 


>» (include macro) 

>>> macro-name 

This instructs the assembler to assemble a 
the named macro at the present location* 
section on MACROS. It may be labeled. 

Variables 

Labels beginning with "j“ are regarded as VARIABLES* They 
can be redefined as often as you wish. The designed purpose 
of variablets is for use in MACROS, but they are not confined 
to that use. 


copy of 
See the 
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the: assembler 


IfiiiMMi [o a variable is Impossible (with correct 

■ ■•nilnii Iilh I ln' asscinbler will assign some value to it. 

■ bill t fi, :i VimLiLIm Hhooid be defined before it is used. 


ti lit I fi use variables for backwards branching, 

to in|‘ I III- fiaiuf at numerous places in the source. For 

♦ ‘ * (un [• 1 !■ 


1 


l,l)Y 

11^ 



L[)A 

TABLE,Y 

1 


\m\ 

NOGOOD 

A 


JSR 

DOIT 

S 


1 NY 


N 


BNE 

]JLOOF 

/ 

NULUOl) 

LDX 

li-l 

n 

1 lIJMH* 

INX 


*\ 


STA 

DATA,X 

1 ^ 


fd3A 

TBL2,X 

1 \ 


BNE 

]JLOOF 


;BRANCH TO LINE 2 


;BRANCH TO LINE 8 
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Defining a Macro 

A macro definition begins with the line: 

Name MAC (no operand) 

with Name in the label field. Its definition is terminated 
by the pseudo—op The label Name cannot be referenced by 

anything other than >>> Name. 

The conditionals DO* ELSE and FIN may be used inside a macro. 

Labels inside macros are updated each time is encounter-^ 

ed . 


Error messages generated by errors in macros usually abort 
assembly* because of possibly harmful effects. Such messages 
will usually indicate the line number of a >>> rather than 
the line inside the macro where the error occurs. 


Nested Macros 

Macros may be nested to a depth of 15. 

Here is an example of a nested macro in which the definition 
Itself is nested. (This can only be done wl’ien both defini¬ 
tions end at the same place.) 

TRDB ItAC 

»> ]2+l 

TR blAC 

LDA J1 
STA 12 
«< 

In this example >» TR.LOCjDEST will assemble as: 

LDA LOC 
STA DEST 
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I MV I MiMii Mm , in. S I' will assemble as: 

i.ha i.iN'ii 

% I A ni .M t 1 
t HA mk; 

M ii\:.y\' 

A iiiMti- ■iHiiiiiiMi In LIU of nestling is illustrated by these two 
. . i H ih t l n t r inn?; (wliere CK = $D3) : 


Mill MAC 

MtA fl\2 
STA 1 I 
- << 

jiiAn mae: 

>» rUKE-CH;]! 

<<< 

MA( lin ii.LiiMMi lu.iy .slso be put in the opcode column, rather than 
t hr wMli Mie following restriction: 

I hi ltir>f Lliree charac[:ers of a name must not coincide 
wiMi any ri'giilar opcode. It is acceptable if two MACRO 
.. h.ivn live same first three characters. 

h)M f |iMon: riie fourth character of an opcode or MACRO 
naini’ iiKidiffes the recognition of the name if it is a 


n . 

M pi 1 id r 

Thus 

\m:. 

i\ MACRO name 

IfICD will not conflict 

wi th 

the 

1 lint 

1 iii^ 

>>> syntax 

Is still available and 

is 

not 


ritih ]iH I In Hil?^ nuM ricticn. The seven character limitation 

Inni hrrii i minViHl . 
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Special Variables 

Eight variables, aantetl [1 through JB* are predefined and are 
designed for cofweniencc in MACROS. These are used in a >>> 
statement. The i ns t rue t iotv; 



>>> NiiME exprl;expr2;expr3,.. 

will 

assign the 

value of eKprl to the variable )l, 

e X p r 2 

to )2, and 

so on. An example of this usage i; 

TEMP 

EQir 

$10 

S\s\\P 

HAC 



LDA 

]i 


STA 

)3 


LDA 

)2 


STA 

J 1 


LDA 

13 


STA 

|2 


«< 



»> 

SWAP 56;$7;Tii:HP 


»> 

SWAP 5lS^00iS6;TEMP 


This program segment swaps the contents of location $6 with 
that of $7, using TEMP as a scratch depository^ then swaps 
the contents of $6 with that of $1000, 

If, as above, some of the special variables are used in the 
MACRO definition, tlien values for them must be specified in 
the >>> statement, Ln the assembly listing, the special 
variables will be replaced by their corresponding 
expressions - 

The number of.values muse match the nLunber of variables in 
the macro definition. A BAD OPEtbUiD error will be generated 
if the number of values Is less than the number of variables. 
Ko error message will be generated, however, if there are 
more values than variables. 




if iH i t n■■ t ii M>ii'HM 1 


M.\CKOS 


I (h I m mill. I i.ni ,ii rt’iM Hoi;;e Other characters in place of 

• h» ‘'t '' » t«i .. ( !m' isi.it’i t) luiitic and the expressions in a >>> 

- > <i.MiKiM I -ii iNifii. , yt)ti may use any of ttiese characters' 


/ . ( 

HI.nHrcd, however j and no extra spaces are 

»♦ I.I 

I *•'<* ‘ ’'111 .pi liieral data. Thos the asserabler will 

I'^' pi » hi. fiillMwini; t ype of tnacro call: 



IHIV nA< 

IMA [I 
MA 

MUV . ( l‘K'J'R) ,Y;J)EST 
MIIV.//1 ;FLAG,X 

♦' I M I ( t i-H ► . i t i (. p f : 

riMhi \\\i 

r,K M.NDMSt; 
r\i 11 
IlKK 

• • IMM NT. r'quo te" I 
*»> I'KlNT.^This is an example'' 

•V* I'lM iVf,''So''s this j understand?" 

I I M M A I I nh : If “nich strings contain spaces or semicolons , 
I ihnv' Mll.l lie hi limited by quotes (single or double). Also^ 
, IM' I -iIn ill! Ii . 1 -! >>> WDAT. 'a" must have the final delimiter. 

{ Ihl'i |r. . Mill, in [31,1 cro calls or VAR statements ^ but it 

I •< . .. Io . 11 r IT I’ in u ! 1 cases.) 
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The Macro Library 

A macro library with two example macro programs is Included 
In source file form on this diskette. The purpose of the 
library is to provide some guidance to the newcomer to macros 
and how they can be used within an assembly program, 

NOTE: All macros are defined at the beginning of the source 
file, then each example program places the macros where they 
are needed. Conditionals are used to determine which example 
program is to be assembled. The KEO opcode allows the user 
to make this selection from the keyboard during assembly. 


;o 


]\i IM III II ^ t n 1MII I I 


TLCIINLCAL INFOKHAT ION 


I I < Ml: t < '\l I III I i(i:iA I I nM 


li* iMMui I > . .I H $A01 when loaded, regardless of its 

• I [ I UM I l«l«l M". N 


i In 1 lopi 

1 M ml pn 

Inters are: 



M All 1 r M 

MKIKCK 

In 

$C,$D 

(always set 

$A01) 

II Mil M 


In 

$E,$F 

(defaults to 

$8000) 

1 IIM ni ■ 

.nil KM 

i n 

$10,$11 




UliiMi vmh ♦' I n I n MAiilC or to the monitor, these pointers are 
M<*‘n.l It f;A00i), They are restored upon re-entry to 

Ml l<1 III 

f I ii»' I . 1 1 I u I n I wiA I inn 

in in riitcj MI IMJN after going to BASIC, use the SYS 52000 

.. 

IIhmimi V III }■.'ll I 1 1 f (HI, for ordinary sized files is of no con- 
I I'Mi in Mir li jnr, but it is important to understand certain 
I nil ri I I ,(1 11 1 f* 1 ni I he handling of large files. ^^ERLI^^'S HIltEH 
I uh M h dnljiili!: to $8000) is an upper limit to the source 
I ilr li is .1 iso an upper limit for PUT files. If a memory 
rMni nr < ui ^ rlui inp, assembly, indicating a PUT line, It means 
I III I'UJ IMr i'xct'oded tllMEM and that HIHEH will,have to be 

I ni f *< I 

I In’ NltM .iuM niu; .iddress equals the present value of BIHEH. If 
.hnln^i, ir^-nnnbly, the object code exceeds BASIC KIMEM (or the 
'^I'tl ln(■l^l'nt^, H one has been specified) then the code will 
nni In’ un IM on [n tiieiriory, but assembly will appear to proceed 
lu-i I I -1 nnipiH sniu t o the screen or printer. The only clue 
MnM fhin Imm hntipoiied, if not intentional, is that the 
nit pn I 'lAVI I tmiiM.iuil is disabled in this event. Therefore, If 
I l l ’dlnp, ini I vni y Imig file is desired, without actually 
I MH I uj' i ruli’^ Mn- usot can assemble over ^E;RLI^i itself. 
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MERLIN 64 MEMORY MAP 


TTFFF 


SYMBOL lAlLE j 

HMI PaFCH {Cjywl) 1 

SDFFF 

rL 

KESWAl PaICH 

SCFFF 

n 

I/O LOCATIONS 




syju7 


M£f?UN 64 


lAOOO 


a 


U0%0 


f9FFF 

END OF OBJECT CODE:- 

MERLIN Hi MEM: SaOOO 

END Of SOURCE:-► 

6EGJNNENG 

OF SOURCE: — 

OaJECI CODE * 

- 1 

4 

SOURCE FILE i 

1 

1 _ I, , 

riFF 1 

[—f MlSC. USA^E 

1 

MAY flE USED ay \m EX£C q 

j 

COMMAWElFOfl OME-TSME 


L/nunfs aui JHauLD 


U NOT BE CHANGED. 


P 

J89F ! 

P UNUSED 

XSG"’ ^ 

P MISC. USAGE 

S7FF 1 

CT 

1 

! SCREEN MEMORY 

tiff j 

^ UNUSEC E LiT DESIGNATED K34 


USR OPCODE KXITJWES 

1 

(USR CKJES A T5t SiiS) 

$33a 1 

- J UNt/SED WAy at USED fOR &rs 

1 

St USB OPCODE BOUIIHEJ 

S35? j 

J KERNAL flAGS AND MJSC, 

1 

MEJJIJN fLAGS $32E.F SS^ THE 

1 

EDITOR'S USER VtCIOG 

X25g ! 


1 

^ UNUSED 

X!FF U 


SIACX AND OfMEB USAGE 

T:‘“F I 

J 

%u i 

;£RO PAGE COMPtFIt UV^GE 


40959 


32768 

■#- 


25e.D 

2559 

23G3 

2207 

2043 

2047 

1023 


820 
SI 9 

&DD 

Sll 

255 

0 


CAN Also BE FOUND 
WITH ■’WO” COJVIMANO 
Fr^OM EDIT mode 
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M( IM f II II ' IM n iMii.L 


Ti:C[iXlCAL IMl'ORj^UTIOX 


iH\u,\ I l|>h 


II- ,«h|im| i.ihlr ( ■- tirinled after asSGinbly unless LST Ol‘'F has 
I -k II Iii'hI-iX I I I iMin's C1Lst in alphabeticai order and then 
«I, MHiiit M. »l .Mili'i . Thf symbol cable is flagged as follows: 


Ml* n n I hi- 1 t ni t ion 

II L.iIh'I deflneLi in a macro (LOOP and OUT in the 

.■■..iiuphO 

V V.iT iaiile (symbols starting with ]) 

/ A symbtil that was never referenced 


hii+inillv, f Im'm* are flagged by setcing bits 7 to A of the 
• < ihIi> 1 1 'i I I' If li ]»v r e : 


r‘ l.j I / Hh bf L 5 H=biC h 


U It, lilt fp In ni'i: during the alphabetical printout to flag 
pitiipid .vitihiil-;, then removed during the numerical order 
j-i ImImhi I III* r;ymbol printout is formatted for an 80 column 
ImImIi'i^ in lot one which will send a carriage return after 

I H I MI.H I '• 


Mnlni', HMU IN U'lili B0 Column Cartridges 

iiiilv Mil’ HA rA.^0 Vldeopack 30 is supported as of this release- 
I'< I iM III I hi* V to command in the section on the EDITOR for 
ih* I lit'. Pill liriw in use 80 column boards with MERLIN- 

till i Pint I in Ml' AltM Program 

hitdllyilil*' t i in M p,u I a t ton parameters are given in the DATA 
Mill' In Mil’ liAhK- iirugram called "MERLIN''. These values are 
pul l [| I III It hir,it i uiis $A006-$A022- These parameters are 
lb' ‘M I 1 Ik’nI .Ml till I (1 w:.; 

MU AilnN MM : PURPOSE 

iMIM VA1 .uk : AND COMMENTS 


i\00fi 0 : Speed of output to printer- 

; Intended for use with the 
: RS212 port to fine tune out-* 
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: put speed* It can be used to 
: compensate for the lack of 
: printer handshake without 
^ having to lower the baud 
: rate. The fastest speed is 
: given by 0 and this should be 
: used for the Commodore 
: printers on serial port. 


A007 

0 

80 column flag for initial 
entry. Selects DATA20 80^ 
column mode if card is 
present and this flag Is 128 
(=S80). 

A008.A0(S9 

: 0,10 (SA00) 

: Default source address - must 
: not be below $A00* 

A00A,A00B 

; 0.128 ($8000) 

' Default HIMEM and object 
i address. 

A00C,A00D 

0,10 CSA00) 

End'of source pointer. Must 
equal default source address 
upon entry. 

A00E ; 

: 94 CS5E) ; 

: Editor's wild card. 

A00F ^ 

; ^ : 

1 Number of fields in symbol 

1 table printout. 

A010 ; 

47 (52F) : 

Search character "/" for 
'‘Update source"' question. 

A011 : 

15 <5F) ; 

Border color. 

A012 : 

15 (^F) ; 

Background color. 

A013 : 

144 ($90) : 

Character color. 

A0U : 
A015 ; 
A016,A0L? : 

6 : 

16 ($10) : 

0,0 ; 

RS232 control register. 

RS232 control register. 

RS232 optional baud rate 


(Lo,hi - rarely used) 


7A 
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r\v' ( n 

I.'ll IVHlI) ; 

; Repeat all keys if $80, but 
; not if 0- 


t h J : 

: Number oE lines per page (for 
: PRTR). 

AVI' 1 A 

/ 

Number of lines to skip at 
page end. If this is a 0 a 
fomfeed ($C) is sent to the 
printer (for PRTR.)* 

1 

IIVl (5M(f) : 

: Number of characters per line 
; (for PRTR)- 

1 AV^h 

1 

1 ,'(i C5(iH) 

Should be 128 if printer does 
its own C/R after printing 
the number of characters in 
$A01B, else 0. 

1 AV^ 1 »^ 

1 

. 0 ; 

1 

: Sends a linefeed after C/R if 
: this is $D-13 and not if 0. 
i Values other than 13 or 0 
: must not be used. 

* f 

f 

0 

i If this is 32=$20 then Commo- 
: dore ASCII will be converted 
: to standard ASCII upon output 
: to the printer. This is used 
: mainly for 3rd party printers 
: on the RS232 port. 

i jM(tl 1 

: ‘1/ (Sf)l) 

If this is 97 then characters 
sent to a printer will be 
echoed to the screen* If 0 
then there is no echo. Other 
values must not be used- 

At'-'tl ASrt.'.' 

■ lA , '0, n 
; (t./; 1 A ,?1 !■■) 

: Default tabs for editor and 
: assembler 
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Error Messages 


BAD OPCODE 

Occurs when the opcode is not valid (perhaps misspelled) 
or the opcode is in the label columni. 

BAD ADDRESS MODE 

The addressing mode Is not a valid 551^ instmctiorif for 
example, JSR (LABEL) or LDX (LABEL),Y- 


BAD BRANCH 

A branch (BEQ, BCC, etc) to an address that is out of 
range, further away than +127 bytes- 

NOTE; Host errors will throw off the assembler's 
address calculations- Bad branch errors should be 
ignored until previous errors have been dealt with. 


BAD OPERAND 

An illegally formatted operand. This also occurs if you 
"EQU"‘ a label to a zero page number after the label has 
been used. It may also mean that your operand is longer 
than 64 characters, or that a comment line exceeds 64 
characters. This error will abort assembly. 
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TKCHNiCAL INFORMATION 


likM I MAM ♦OOUMtl 

iiM Mil’ l li'if Hie assembler finds two identical 

I aFi< I 


m; UmM V I tM I 

MM ii ii-airiMy caused by one of three conditions; 

,iMM » indi’ [{>0 tarj;ej symbol table too large, or a PUT 
I Mr r r riid hiK beyond HIHEH- See "Special Note" at the 
r ii.| III MM f;ocl ion. 


tblMbiUN I.AM'.I^ 

Mhh ^iioiMuiii refers to a LABEL that does not exist. 
Ml Mi nlsn occurs if you try to reference a MACRO defini^ 
j lull by nnylhing o ther than >>>. It can also occur if 
Mir I iM (M onced label is in an area with conditional 
I y OFF. The latter will not happen with a MACRO 
dfM MM T i on » 


OiM riACIfn 

Ri M'ii'iii i‘ by >>> to a label that is not a MACRO. 


niMM irjL hH\nm 

M.itiioi nosted more than 15 deep or conditionals nested 
moil’ I livin d deep. 


bAI» IdM ■ 

MMu \h nuiiiod by a PUT inside a macro or by a PUT 
Mifl i(r u niiMic I PUT file * 
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BAD "SAV" 

This is caused by a SAV inside a macro. 


BAD INPUT 

This results from either no input (RETURN' alone) or an 
input exceeding 37 characters in answer to the KBD op- 
codecs request for the value of a label. 


BREAK 


This message is caused by the ERR opcode when the ex 
pression in the operand is found to be nonzero. 

BAD LABEL 

This is caused by an unlabeled EQU or MAC* a label that 
is too long or one containing illegal characters. 


full” error 
problem and 

ERROR MESSAGE: "ERR: MEMORY FULL”- Generated immediately 
after you type in one line too many- CAUSE: The source code 
is too large and has exceeded ^E:RLIN"s HIMEM (normally $80(^0) 
REMEDY: Raise MERLIN"s illMEM (see the section on the UXMEM 
command) or break the source fils up into smaller sections 
and bring ttiem in wlien necessary by using the ’PUT" pseudo¬ 
op. 

ERROR MESSAGE: "MEHORV FULL IN LINE: n". Generated during 
assembly. CAUSE: Too many symbols have been placed into the 
symbol table, causing it to exceeti nvailible space. REMEDY. 
Make the symbol table larger by using the SYM command to 
lower its beginning address. 


Special Note ^ Memory Full Errors 

There are four common causes for the "memory 
A more detailed description of this 
some ways to overcome it follow. 
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♦ ♦MM»h rit Ai I IJnu- , |iii( no object code will be generated 
< I hi i Mill ln' no n(^ jcr I I nf o rma t ion d is play ed o n the EXEC 
III iiM t I :\\\\\ nh P'S t rode generated from an assembly woold 
h. ► I » f d»-I « Im hynnlnM table or BASlCs HIMEM- Also can be 
, I .1 li I IM I Mo fn i tig, Loo large, REMEDY: Lower MERLIN" s 
1.1 Mil I Im’ nlipMi code directly to disk, using the 

h i I » ihl'T^ n|i 


Mm h IM Ml (in iMtms on the first pass and while the 
11 . (Mhlii h iMMiro.sing a PUT file, the error message will 
loMiaM Mil ( I IM" iinjubnr preceded by 'i>'‘ in the PUT file- To 
Hni oil I ill M iir i>l the main program is In effect (which will 
)ir ihr rin liiir), simply type 'V'^RETURN> and quickly stop 
Mi. Mi.ifitji I In' I 1 1 line listed will be the active line- 


Mi MH h I|I 


I .. 


I :l I 

M 'iIM'M 


Cniiiiiicidci r e Key 

COMMENTS 


II .'t — Note that the proper entry format is 

byte-sp3ce”byte etc* 

i I Disassemble 20 lines beginning at 

$1000, ASCII indicated at right. 


100011 Disassemble 40 lines beginning at 

$1000, ASCII indicated at right, 

MuM liili I n Continues disassembly at current 

;i d d r e s s , 


I000h 


Does a hex dump of 8 bytes at $1000* 
ASCII Indicated at right. 


h 


h alone continues the dump from 
turrtuiC address. 
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Multiple h's 

Dii/iips multiple 8 byte blocks. 

$1(100. 1100h 

Does a hex damp of the designated 
range. Note comma Is used here* 

$1000<—2000.201Fm 

Moves range $200^(i-$201F to $10^0. 
This supports both upward and 
downward tnoves- 

$1000,20002 

Zeros this range* 

$1000<—2000,201Fv 

Compares the range $2000-$20IF with 
that starting at $1000 and displays 
contents of both when differences 
are found* 

$1000g 

Jumps to program at $1000. Return by 
RTS* A BRK will also return with a 
register display- 

St 

Returns to editor, , 

$q 

Returns to EXEC mode. This is a 
'"safe" return even if the zero 
page locations have been changed. 
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SOURCEEOR 


M t|l|i I I IM IM 


r Ik I I <o! M* [ I MM 

ikHMn ui!N( I rj ,1 !ii) [ill i si lea ted and easy to use disassembler 
»li>. I^fkiil ,i-i .1 fnilir: I it i n ry to create MERLIM source files out of 
I.Immv .. usnaXly in a raatter of minutes- 


II.* I M*. M ilJHi I 

I Miiltn.l.Ut(K c an l>e LQADed and RUfJ from BASIC or can be run 
M.itik|.t Ml HMN's "G" command. It requires the standard 
.. A0 column screen to be in use when it is run, 

,* 'ailNN I.KnK (iiay also be run as follows: 

I (lAN "!iunHCi:ROR.O'\8,l 
^Y^ I /* AlA'Mi 

■ajllKri ltnk ewerwrites part of MEELIt^ andj after exit, a 
SY'i will re-enter SOURCEROR not XiERLIN, MERLIN 

itiiin I 1)i' I c Ioaded , 

i III! i tktry you are asked if you want to load an object 
IIIm, Ymi must svjpply the full file name, including the 
ci [| M(iy, IE this option is selected then the object 
i\lv will III' loaded to a particular location C$A00), and 

tiki’ . .. address will be placed just following thatp 

HI IN I N 'i iiKMUi format will infom you of the range of 
iiuniHHv ikniinally occupied by the program. You should 
♦I ( III I il I sasscinhly at this beginning address, 

Yctkk will hi- Lold that the default address for the source 
J I 1 1 ^ If! This was selected becuase It does not 

« Mill Mil wiih the addresses of most binary programs you 
in/iy wl'di fw dfsnssemble. Just press RETURN to accept 
I h I ri ili'luMlt adclress. Otherwise, specify (in hex) the 

.uht|iM|f, ycMi Wi'lnl, 

f* fh'Mt , ypiM will he asked to hit RETURN if the program to 
|m. d |m*i fuuuiih 1 rd Is at Its original (running) location. 
Ml ciHiMi s|iiM’ily In Hex, the present location of the 
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code CO be disassembled. Finally, you will be asked to 
give the ORIGINAL location of that program. 

When disassembling, you must use the ORIGINAL address of 
Che prograsn, not the address where the program currently 
resides. It will appear that you are disassembling the 
program at Its original location, but actually, 
SOURCEROR is disassembling the code at its present loca¬ 
tion and translating the addresses. 

Lastly, Che title page which contains a synopsis of the 
commands to be used in disassembly will display. You 
may now start disassembling or using any of the other 
commands. Your first command must Include a Hex ad¬ 
dress, Thereafter this is optional, as we shall 
explaini 

At this point, and until the final processing, you may 
hit RUK/STOP and RESTORE to return to the start of the 
SOURCEROR program. If you hit RUN/STOP-RESTORE once 
more. you will exit SOURCEROR and return to BASIC. 
Using RESET assumes you are using the Autostart monitor 
rom. 


Commands Used in Disassembly 

The disassembly commands ace very similar to those used by 
the disassembler In the MERLIN monitor. All commands accept a 
4-dlgit hex address before the command letter. If this 
number Is omitted, then the disassembly continues from its 
present address. A number must be specified only upon 
initial entry. 

If you specify a number greater Chan the present address, a 
new ORG will be created. 

More commonly, you will specify an address less than the 
present default value- In this case, the disassembler checks 
to see If this address equals the address of one of the 
previous lines. If so, it simply backs up to cbac point. If 
not, then It backs up to tbe next used address and creates a 
neu'oRC. Subsequent source lines are "erased". It is gen- 
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» I-I I I , tn iivolc! new ORGs when possible. If you get a 

Mhw nlM. Mi»l ihsii t wanL It, try backing up a bit more until 
. M 1 I MU lull, 1 , 1 'I p,(’[ .1 n(fw OHG upon disassembly . 

I iipiiiM tni| |)<"u 1 [ |H inns 

I M ( . M 

III In S-j I hi-“ main disassembly command* It disassembles 20 
M nnn n| t'ode. It may be repeated (e.g* 2000LLL will 

.11 1 p 60 lines of code starting at $2000)- 

II un EHeival Opcode is encountered, the bell will sound 
ind ti|)cnile will be printed as three question marks In 
ll.iPitilivK format- This is only to call your attention to 
I Ih' ni Inal ion. In the source code Itself, unrecognized 
• q.i are converted to HEX data, but not displayed on 

t lu' ‘P I pen . 


II (Ih'K) 

rbl't rnMies the HEX data opcode- It defaults to one 
livU' rii data- If you insert a one byte (one or two 
d I g I f 'I J hex number after the H, that number of data bytes 
will y.uiierated - 


I t IH«I ) 

Ihln uMeiiipts to disassemble the data at the current 
ubhi'-.ft ns nn ASCII string- Depending on the form of 
I hi’ dni.f, this will (automatically) be disassembled 
im-h'i I hi‘ pseudo opcode TXT ct DCI- The appropriate 
<li Mmlii'i or ^ is automatically chosen- The disassem” 
hiv will I’ud witen the data encountered is inappropriate, 
wliiiii h( h.ir.irt nrs have been treated, or when the high 
hi I Ml Hir‘ dal.I changes- In the last condition, the TXT 
Mp< M.|.« { >, -uH MUhi I: leal ly changed to DCI. 


83 




MERLIN Users Manual 


SOURCEROR 


Some Limes the change to DCI is Inappropriate. This 
change can be defeated by using TT instead of T in the 
command, 

Occasionally, the disassembled string may not stop at the 
appropriate place because the follou'ing code looks like 
ASCII data to SOURCEROR. In this event, you may limit 
the number of characters put into the string by Inserting 
a ono or two digit he:t number after the T command. 


W (Word) 


This disassembles the next two bytes at the current 
Jocation as a DA opcode- Optionally, if the command WW 
is used, these bytes are disassembled as* a DDB opcode. 
Finally^ if W- is used as the command, the two bytes are 
disassembled in the form DA LABEL~1. The latter is often 
the appropriate form when the program uses the address by 
pushing it on the stack- You ijay detect this while 
disassembling, or after the program has been dis¬ 
assembled. In the latter* case, It may be to your advan^ 
tags to do the disassembly again with some notes in hand. 


liousekceping Commands 


/ (Cancel) 

This essentially cancels the last commattd. More exactly, 
it re-establishes the last default address (the address 
used for a command not necessarily attached to an 
address). This is a useful convenience which allows you 
to Ignore the typing cf an address when a backup is 
desired. As an example, suppose you type T to dis- 
assemble some text. You may not know what to expect 
following the text, so you can just type to L to Look at 
It- Then if the text turns out to be followed by some 
Hex data (such as $0D for a carriage return), simply type 
/ to cancel the L and type tlie appropriate H conimaad. 



Ml MI I H M • > k ' 11 k UM .1 


50URCER0R 


l| { If.11 * I 

... il I iHifi t y and goes to the final processing 

h I I nkffHn.iMr, Tf you type an address before the Q, 
Hm t-lih ( nn pnfiLtrr Js T>acked to (but not including) that 
(••till hr I Ml tin- |krocessing^ If, at the end of the 
*H ‘ tr n'luli j V ^ t iir cM sassembled lines Include: 

I hi R0 JHP $E003 

r\*h A'l Ill: 94 LDA $94BE,Y 

<ni»( I 111’ I a *11 M Til' is jus t garbage j type 2344Q* This will 
I Mil I' I M(m 1.1 If line, but retain the first, 

I I U'l' I t' I I n r ’mM 

AHri I hr T/ ■ IMiiiii.iiirl ^ | ho program does some last minute pro- 

*‘1 1 hi- bled code. If you hit RUN/STOP-RESTORE 

Hi Mil.I E hiir ^ will return to BASIC and lose the dls- 

i| iMi r III ||< I r <1 I Ml I r , 


I hi’ |H HI r n i j lijf (iiay lake from a second or two for a short 
)• ♦'Ht ♦ Hill, (n luui’ial minutes for a long one. Be patient, 

^diiMi I lii< fii iir r?;:i' nr. i-s done, you are asked if you want to 
-♦h-m Mil iMiiirH. 11 so, you will be asked for a file name, 
ohMih t ioi|f ul I I nppnnd the suffix '\S” to this name and save 

( t f M It Ml . 

Mi»- dll M iMird wM I hr the one used to RUN SOURCEROR, Replace 
Mil, dtiil I I I Ji f M ytni want the source to go on another disk, 

(H ImmI ,m (hr d 1 n.i'ssrmh 1 ed sourcej RUN MERLIN, 
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Dealing with the Kinished Source 

In most caseSj after you have some experience and assuming 
you used reasonable care, the source will have few, if any, 
defects. 

You may notice that some DA^s would liave been more appro^ 
priate in the DA LABEL-i or the DDB LABEL formats. In this, 
and similar cases, it may be best to do the disassembly again 
with some notes In [land. The disassembly Is so quick and 
painless, that it is often much easier than trying to alter 
the source appropriately. 

The source will have all the exterior or otherwise un¬ 
recognized labels at the end in a table of equates. You 
should look at this table closely. It should not contain any 
zero page equates except ones resulting from DA^s, JHP'^s or 
JSR^s, This is almost a sure sign of an error in the disas¬ 
sembly (yours, not SDURCEROR's). It may have resulted from 
an attempt to disassemble a data area as regular code. 

NOTE: If you try to assemble the source under these con¬ 
ditions, you will get an error as soon as the equates appear. 
If, as eventually you should, you move the equates to the 
start of the program, you will not get an error, but the 
assembly HAY NOT BE CORRECT, It is important to deal with 
this situation first as trouble could occur If, for example, 
the disassembler finds the data AD 00 8D- It will disassem¬ 
ble It correctly, as LDA $008D. 

The assembler always assembles this code as a zero page 
instruction, giving the two bytes a 5 SD. Occasionally you 
will find a program that uses this form for a zero page 
instruction. In that case, you will have to insert a char¬ 
acter after the LDA opcode to have it assemble Identically to 
its original form. Often It was data in the first place 
rather than code, and must be dealt with to get a correct 
assembly. 


66 



fh IM I W Nmm ■, M.mmi.m I 


SOURCEROR 


1111• f * iiH H y lull M<-? Ti SCI g e 


Uhrn 

1 hr* 

■;on r 

c 0 file 

reaches within 

$600 

of the 

start 

of 

M IIIIH 1 

1 MOK 

yon 

will see "MEMORY FULL" 

and 

"HIT A 

ICEY'* 

in 

1 H *• 1' 1 

M’ 1 

' n 1 lun t 

. When 

you hit a key 

, SOURCEROR 

will 

go 


Til I lie final pro-cesslng- The reason for the $600 
r.'>!' i)u\\ SOURCEROR needs a certain amount of space for 

I li III |i I i>rr'; i ng - It is pos-sible (but not likely) that part 
► will be overwritten during final processings but 

iIMn ■dunild not cause problems since the front end of 
.otllH'iKnu will not be used again by that point. There Is a 

.. override provision at the raeiDOry full point. If the 

^ vi'u hit Is CTRL-O (for override), then SOURCEROR will 
I ru m n fur another corntnand. You can use this to specify the 
eliding point. You can also use it to go a little 
f T fnu than SOURCEROR wants you to, and disassemble a few 
. Hnes- Obviously, you should not carry this to extremes 

lii’nM'iMbui , after exiting to BASIC a SYS 52000 will reenter 
.hniJ|{(;i';RnR (not MERLIN, which has been overwritten). 

I In* I.ABELIhl program 

nur ol the nicest features of the SOURCEROR program is the 
uiituiiuii it’ assignment of labels to all recognizable addresses 
I*’ Till* 111 nary file being disassembled. Addresses are recog— 
''I 'd !>v being found in a table which SOURCEROR references 
dm ihr disassembly process. This table is on the disk 

und-'i fill' name LABELS. 0. For example, all JSR $FFD2 

.hum within a binary file will be listed by SOURCEROR 

.iti Ihu rum MIT. This Cable of address labels may be edited by 
UN I Mg Mil* |it (3|;ram LABELER. 

In HNu I a hr In r, lUIN LABELER. 


I .1 hr I i*i I I I MiiMii. I nd S 
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Q^QUIT 

When finLshed with any modifications yon wish to make to the 
label table, press "Q" to exit the LABELER program. If you 
wish to save the new file, press ""S'- Otherwise, press 
ESCAPE to exit without saving the table, for instance, if you 
had only been reviewing the table. 


L:LIST 

This allows you to list the current label table. After "L", 
press any key to start the listing- Pressing any key will go 
to the next page; CTRL-C will abort Che listing- 


D:DELETE LABELCS) 

Use this option to delete any address labels you do not want 
in the list* After entering the D command, simply enter the 
NUMBER of the label you want to delete* If you want to 
delete a range, enter the beginning and ending label numbers, 
separated by a comma* 


A:ADD LABEL 

Use this option to add a new label to the list. Simply tell 
the program the hex address and the narae you wish to 
associate with chat address. Press RETURN only, to abort 
this option at any point. 


f:FREE SPACE 

This tells you how much free space remains in the Cable for 
new label entries* 
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Ahi’M t 

-terminate an operation prematurely. 

A* « f 

“locate or retrieve data. 

Aitinu \ 

-a memory location. 

Al tM>|( 1 HIM 

-a method of solving a specific problem. 

Ai 1 iH a i m: 

"Set aside or reserve space* 

AM 1 J 

“Industry standard system of 128 computer 
codes assigned to specified alpha-numeric 
and special characters. The Commodore 
uses a somewhat non-standard ASCII* The 
main difference is the reversal of upper 
and lower case letters. 

MAM' 

“in number systeens^ the exponent at which 
the system repeats itself; the number of 
symbols required by that number system* 

lU riAKY 

-the base two ^number system, composed 
solely of the numbers zero and one* 

h 1 1 

-one unit of binary datSj either a zero or 

a one. 

lUiAUi II 

-resume execution at a new location* 

Milt I 1 M 

-large temporary data storage area- 

irn 1 

-liex representation of eight binary bits* 

1 A|l|t t 

-flag in the 6510 status register* 

1 IH t' 

“tJtiy piece of silicon or gertnanlum con¬ 
taining many integrated circuits* 

1 M|H 

slang for data or oiaciiine language In- 
iH ructions. 
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CTRL 

'abbreViatioQ foe control or control 

char.icti^r- 

CURSOR 

-character j usually a flasliing inverse 
space ^ which inarks the position of the 
next character to be typed. 

DATA 

-facts or information used by, or in a 
computer program. 

DECREMENT 

-decrease value in constant steps. 

DEFAULT 

-noroinal value or condition assigned to a 
parameter if not specified by the user. 

DELIMIT 

“Separate^ as with a: in a BASIC program 
line. 

DISPLACEMENT 

-constant or variable used to calculate 
the distance between two memory 

locations - 

EQUATE 

*-establish a variable. 

EXPRESSION 

-actual, implied or symbolic data. 

FETCH 

-retrieve or get. 

FIELD 

-portion of a data input reserved for a 
specific type of data. 

FLAG 

-register or memory location used for 
preserving or establishing a status of a 
given operation of condition. 

HEX 

-the Hexadecimal (BASE lb) number system, 
composed of the numbers 0-9 and the let¬ 
ters A-F. 

lilCH ORDER 

-the first, or most significant byte of a 
two-byte Hex address or value. 
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limn 

I M< It I rtr \n 

I M I I I A) I .'1 

I /M 

Mill IM Ai I 

I rivt MI 
I Mil I 

I mil Mr 
I HU himII r 

I Ml 

l\M Kn 

HM fHMMHiLI'r; 

IIMII 

IliilM 
m IIIIM I 

iLM mull I 


-vt^cnor address to an I/O routine or port. 

"iticrease value in constant steps. 

-set all program parameters to zero^ nor¬ 
mal^ or default condition. 

-input/output. 

^method of interconnecting peripheral 
equipment. 

-change to the opposite state. 

-name applied to a variable or address, 
usually descriptive of its purpose. 

-slang; see table. 

-the secondj or least significant byte of 
a two“byte Bex address or value. 

-least significant (bit or byte) one with 
the least value. 

-in assemblers, the capability to *'call“ a 
code segment by a symbolic name and place 
It in the object file. 

:m)|| -heart of a microcomputer. (In the 

Commodore the 6510 chip). 

-algorithm returning the remainder of a 
division operation. 

-particular sub-type of operation- 

(lottlon of a program devoted to a spec- 
itfe function. 

Tiyinbiilic abbreviation using characters 
lii'l]Mul in recalling a function¬ 
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MSB 

-mosL significant (bit or byte), one with 
the greatest value. 

i™ll 

OBJECT CODE 

"Ulthout value# 

-ready to run code produced by an assem¬ 
bler program # 

OFFSET 

-value of a displacement- 

OPCODE 

-lustruction to be executed by the 6510. 

DPERAl^D 

“data to be operated on by a 6510 Instruct* 
tlon. 

PAGE 

-a 256-byte area of memory named for the 
first byte of its Hex address# 

PARAMETER 

-constant or value required by a program 
or operation to function. 

PERIPHERAL 

^external device. 

POINTER 

-memory location containing an address to 
data elsewhere In memory. 

PORT 

^physical interconnection point to per¬ 
ipheral equipment. 

PROMPT 

-a character asking the user to input 
data» 

PSEUDO 

-artificial, a substitute for. 

RAH 

-random access memory# 

REGISTER 

-single 6510 or memory location. 

RELATIVE 

-branch made using an offset or displace- 
ment - 

ROM 

-read only memory. 
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^ 1 i,rj u 1 1 

’bit seven of a byte; negative if ^alue 
greater than $80. 

niiM 1 M mi: 

’data entered into an assembler which will 
produce a machine language program when 
assembled. 

M 1 

"temporary storage area in RAiM used by the 
6510 and assembly language programs- 

<1 MM \ni 

-a group of ASCII characters usually en¬ 
closed by delimiters such as or ", 

fMMnni. 

-symbolic or mnemonic label. 

hYIM AX 

-prescribed method of data entry- 

1 A in 1. 

-list of values, words, data referenced by 
a program. 

liiKi.l 1 

-switch from one state to the other. 

VAN 1 AllLK 

“alpha-numeric expression which may assume 
or be assigned a number of values. 

VI ( KHi 

-address to be referenced or branched to- 
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n M I IMIS 


1 * ► I ai,.i ( t i’ f 

Hi 1'► i-i am in provided to enhance the use of MERLIN as a 
in io’i if I cKt editor- It will automatically fonnat a file 
Inin |fa 1 ,if;raphs using a specified line length- Paragraphs 
tn n iviiulnd by empty lines in the original file. 

In 11 PM* FUUMATTER, run it from the EXEC mode ’"G" conimand- 

' liHt' It Is intended for use with general purpose text files 
I I will overwrite the assembler portion of MERLIN. To 

Mr,f,rmhli* a file MERLIN will have to be reloaded. To format a 
t f I i* which is in memoryj issue the USER command from Che 
ml I I 1M . 

I Im' f o r rita t ter program will request a range to format. If you 
1iitu t^uncify one number^ the file will be formatted from that 

linn Id the end. Then you will be asked for a line length, 

vliMh ifiusi he less than 250- Finally, you may specify 
'Inihi't yon want the file justified on both sides (rather 
I h,id hi*5 1 on the left). 

J hi» Mi ! 1 L tiling done by the program is to check whether or 

... line of the file starts with a space. If not,, a 

Is InsHiuted at the start of each line. This is to be 
M'dil In pjve a left margin using the editor's TAB command 
h»*l*Mi* M*ilng the PRINT command to print out the file, 

luiiiifiMiu nsdJi inverse spaces for the fill required by two- 
pnit 11 i ca(, Lon . This is done so that they can be lo" 

l aiidl Mild inmdVi'd if you want to reformat the file later. It 
I »» I iiip'« I f nil that you do not use the FIX or TEXT commands on 
a I M f aliir ji has laeen formatted (unless another copy has 
lii'i‘ii oavid). Fnr files coming from external sources, it is 
duiHi thli* Ml \ It;;!: use the FIX command on them to make sure 
( lit* V hMVi* I hi* furui expected by FORliATTER, For the same 
It ! ?t advisable to reformat a file using on<)pp<5ft 
|int M M. I r I i»M pi Ini to ai\y edit of the file- 
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Don't forget to tise the TABS command before printing out a 
fo raa 11ed file * 

CHRaEN 80 

CILRGEN 80 Is a 80-colunin character generator which is de¬ 
signed specifically to allow the use of MERLIN with a 80 
coluiTin by 24 line display on the Hi-Res screen^. 

TV sets do not provide sufficient resolution for use with 
CHRGEN 80, thus requiring use of a display monitor for 
satisfactory results. 

To use CHRGEN 80, you must first RUN it from MERLIN's EXEC 
mode with the "G'" command. This will reset the source address 
to $4000 (above the Hi-Res screen which must be used by 
CHRGEN 80)* This, of course, will delete any source file in 
memory at the time. Once it has been RUN, you can Invoke it 
at any time by typing "USER" from the editor* 

To exit CHRGEN 80, simply use to return to the EXEC Mode, 

Upon return to the editor, you can reconnect it by typing 
"USER" again. To permanently remove CHRGEN 80 in order to 
free up the area normally used by long source listings, you 
will have to RUN MERLIN again. 

If the USER vector has been written over by some other USER 
routine, it can be reset to point to CHRGEN 80 either by 
RUNing CHRGEN 80 again, or by going to the Monitor {use the 
MON command) and typing in A00G. The latter assumes, of 
course, that CHRGEN S0 is still intact at $A00, 

CHRGEN 80 Includes a version of the FORMATTER program. To 
implement FORltATTER when CHRGEN 80 is connected, just type 
CTRL^’F or F3 from the editor's command mode. NOTE: This 
command may not be accepted unless something has been listed 
previously. 

CHRGEN 80 also includes some keyboard macros. Typing the F5 
key followed by certain other keys will produce the keyboard 
macros. These are presently defined for these keys as: 

^ + 
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/ 1 X Y n H I’ [? L S - 0 C A E 


t All I HUl Wlien CHRCHN 80 is 
Mil tniij;ri thnn 96 sectors 
Mir ■;ysl.om. Text files 
I lit V iM r tirvrr allowed to go 


up, you must not load any source 
or it will overwrite MERLIN and 
do not present this danger since 
beyond HIMEM, 


•lilt , XU KIM XL and STRIP 

Ml I i M y lu ograins XREF, XREF-XL and STRIP provide a convenient 
«i( nia Ell ^»enerating a cross-reference listing of all labels 
.. within a MERLIN assembly language (i-e., source) 

III Ilf;I .leii. 


-ir li .1 listing can help you quickly find, identify and trace 
‘'Mui'fi thronghout a program. This becomes especially im- 
piut.itil when attempting to understand, debug or fine tune 
pMi I iiHis of code within a large program* 

I hr MLRKIN assembler by itself provides a printout of Its 

•jyinlMif table only at the end of a successful assembly (pro^ 
viilrd f lint you have not defeated this feature with the LST 
DM juiriulo op code). While the symbol table allows you to 

M'f* whnc the actual value or address of a label is, it does 

mil .illow you to follow the use of the label through the 

I I I I 4 ; I > III! . 

Ml 1 11 whi're XREF, XREF*XL and STRIP come in* 

MM I' yjvrii you a complete alphabetical and numerical printout 
• *i hihrl usage within an assembly language program with a 
l»'U|Mh III up to approximately 1,000 lines {heavily commented) 
Ml ’,000 M iir s. ( I igh t ly coramented), 

MM I I Ii.mmIIus "extra^large” files of up to three or four 
I m>H'I t I lir 'M ol those handled by XREP by storing the gen- 
f iiiti-i riMtirence table on disk and printing it out 

I M r I 

*||l♦M (Miividr*) n liK'tlmd of reducing file si2:e by removing 
I hmmiim Mi l III Mil ijiiii I r r code - 
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Sample 

MHRLLM Symbol Table Printout: 



Symbol 

table “ alphabetical order; 



ADD 

^$F786 BC -$F7B0 

BK 

=$F70b 

Symbol 

table - numerical order; 

• 


BK 

-5F706 ADD 

BC 

-$F7B0 


Sample MLRLIC^ XREF Printout: 

Cross referenced symbol table “ alphabetical order: 


ADD 

=5F7a6 

101 

185* 

BC 

=$F7B0 

90 

207* 

BK 

=$F706 

104 

121* 


Cross referenced symbol table - numerical order: 


BK 

=$F706 

104 

121* 

ADD 

=$F786 

101 

185* 

BC 

=$F7b0 

90 

207* 

As you 

can see from 

1 the 

above example the 


actual value of the label is Indicated by the slgn^ and 
the line number of each line in Che source file that the 
label appears in is listed to the right of the definition- 
In addition, the line number where the label is either de¬ 
fined or used as a major entry point Is suffixed ("'flagged") 
with a 


An added feature is a special notation for additional source 
files that are brought in during assembly with the PUT pseudo 
opcode: ''134.82"\ for example ^ indicates line number 134 of 
the main source file (which will be the line containing the 
PUT opcode) and line number 82 of the PUT file, where the 
label is actually used- 
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^ M I M IH ( I on r> 


\ Iff 1 11 (it Ml fOJhf's Execqtdve Mode, make sure you^ve S)aved 

1 h»' I I Ir Unit you're working on and select the D)rive no. 

r Inf I h. HKIUJ N disk is in. 

( , |fr c ' ,03(1 tiien "XREf <RETLJRN> (Your fdle in memory 

‘Ml MOW 1H ‘ I' r a s tu j *) 

' !''• I irtnd your file. Initialize your printer with the 

i|i|UopiiuM' rORT or PRTR command (XREF is usually, but 

iHii iini r's sa r t 1 y , a printer oriented command). Use PRTR 0 
M you pi;!t WriT^t screen output. 

'< l v|if' 1 11 [ Im" appropriate USER command: 

||%M( ri int assembly listing and alphabetical cross 
3olr‘rence only- (USER has the same effect as 
IfSI'lH 0), 

liM P I isit assembly listing and both alphabetical and 

iMiiLio r i cal ly sorted cross reference listings. 

lUd H |]o not print assembly listing but print alpha- 
lifiic.ii cross reference only. 

i liu no!: print assembly listing but print both 
. 1 1 plhiliet ical and numerical cross reference 
list Ings. 

li’iiP I mhiiii.mhI fi 0-3 (above) cause labels within conditional 

. inhlv iM'.iN wll h the DO condition OFF to be ignored and 

imm pi luip‘d In [ h(' cross reference table. 

I li* M III- uddlrioual USER commands (4-7) that function the 

• Hmi in UM R 0 I, i'scept that they cause labels within con- 
Mi inn H uMfu'iiilily areas to be printed no matter what the 
id Mu- lin rif-t t lug is. The only exception to this Is 
Mtui lulu I', df-l hud in such areas and not elsewhere will be 
I H M Mid 

M'»N »MU III Iy . h.mp^i' l.he USER command as many times as you 

♦ 'ill ii ^ Mom if'ifK ] to USER 2)- The change is not per— 
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m^jnerii: unctl you enter the ASM command (below), 

5, Enter the ASM command to begin the assembly and printing 
process. 

CAdTlOWS for the use of XREF 

XREF works by examining the listing output of Che assembler* 
On the second assembly pass^ It builds a cross reference list 
beginning at HIMEM instead of creating object code tliere* 
(If direct assembly to disk is selected by the DSK opcode, 
however, the object code will be generated). The list uses 
six bytes per symbol reference which can use up available 
memory very quickly. Thus, on long files, you should set 
illHEM as low as possible, (The command can be used to 
find the end of the source file, which represents the lowest 
position you can sat HIMEM). 

Since the program requires assembler output, code in areas 
with LSI OFF will not be processed and labels In those areas 
will not appear in the table. In particular, it is essential 
to the proper working of XREF that the LSI condition be OM at 
the end of assembly (since the program also intercepts the 
regular symbol table output). For the same reason, the F3 
flush cointEiand must not be used during assembly* The program 
attempts to determine when the assembler is sending it an 
error message on the first pass and it aborts assembly in 
this case, but this is not 100% reliable. 

Macros require speclaL consideration. Since the syntax in 
these structures can become very complicated, XREF may get 
confused and cause assembly to stop. This usually happens 
when lines containing tlie >>> pseudo opcode are followed by 
string literals or parentheses and you have chosen to 
suppress printing the expanded form of the macro Ln your 
assembled listing with the EXF OFF pseudo opcode. You can 
get around this problem by printing out the assembly listing 
first in Che usual manner (with the symbol table suppressed 
by tlie LST UFF (iseudo opcode) and then printing out just the 
cross reference table with ExXP OM and using tlSbU 2 or 3* 

Another thing to look out Cur when using macros is tU& fact 
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Mill liiln'lji ill"fit!(id within macro definitions have no global 
in> Mill!)', .nut Hire therefore not cross-ref erenced * 

<-^Hacro definition 


<-“-fieg. of program 
<-Macro call 

hi I hi- ihovo example, variable GLOBAL will be cross ref- 
Mii'mi"ilj Imii lijcal label DONE will not 


hi 1 MAC 

CMP {I\l 
PNE DONE 
ASL 

htMlI <<< 

»> DEF. GLOBAL 


MM I y,\ hi:U nic t ions 

vIM r Kh \ r, designed to handle files three to four times as 
hn)M" ,\f\ [ bijse handled by XREF * 

111 i + iw XHKP.XL, just follow the same five steps In the XREF 
hiik t I III 1 I uiis ox|)lained previously, substituting "XREF •XL" for 
y P I 1 In nIrp 2 . 

MM I .XL Win ks in a manner similar to XREF, except that it 
iM 1 1 i*ii f hi" <ross reference label table to disk in a file 
*fMli'-l XMMFILE (You can delete this file when you are done 
wtph (In- t.ihli')' At the end of assembly, this file is loaded 
I I iiiii d hd^ .Mill placed in memory, overwriting your source file- 
Api i" w |i I M iifd th step 1 , make sure that you^ve saved your 
imiuii" fill" (Itst, because the source file will be deleted 
I I Hill iin-miiiy whr'ii yon return to the editor* 
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CAUTIONS for the use of XREF.XL 

-Tlie source file will be deleted from meniory as explained 
above when you return to the editor. Make sure that you 
have saved your file first* 

-Consider using a blank, disk when using XK£F*XL* The disk 
file generated^ X^R^FILEj can become quite latge* 

-The cross reference label table X*R,F1LE is written on the 
disk in the disk drive last used. If your source file 
contains PUT directives, you will have to make sure XREF.XL 
can find the additional source flies by either moving the 
files onto the blank disk or by specifying a drive parameter 
in the PUT directive, 

-Certain things can cause the XREF program (or CHRGEN 853) to 
be "disconnected*". They can be reinitialized by going to the 
monitor and entering A550G. 

-Unlike XREF, the setting of HIHEH does not affect XREF-XL. 
While building the cross reference table, XREF*XL checks to 
see if it will fit in the space from the source address 
(approximately) to the SYM address, if specified^ or to 
$A000 if not* If it is too large, XREF,XL will quit with an 
OUT OF MEMORY message, 

-XREF.XL will quit with an ILLEGAL DSK ATTEMPTED error 
message If it finds a DSK. pseudo op code in your source 
file* A handy way of avoiding this problem while at the 
same time maintaining the same line numbers in the source 
file is to use the editor to change any DSK directives into 
comments, 


XREF A and XHEF A.XL 

These are ADDRESS cross reference programs and are handy when 
you have lots of PUT files. Since these need only four bytes 
per cross reference instead of sixf they can tiandle con¬ 
siderably larger sources. Also the "where defined" reference 
is not given here because it would ccjual the value of the 
label except for EQUated labels where it would just indicate 
the address counter when the equate Is done- this also saves 
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1 I niN I <lr [ ah sjoace in tabla tor a lacger source* 


s I in r 

lojiK source files, or ones that contain numerous com- 
iiiiiy require too much memory for the cross reference 
i ilih' En Ifu generated. In this case, assembly will stop with 
I In ntlT f)l‘ MKHDRY error message* 

ullUr.y program STRIP allows you to cross reference files 
,t |i|n MH i mn toly twice as large by removing comments from the 
(M H I f o I i I e * 

... STRIP, follow the following procedure: 

I Mulo* sure that you have a copy of your commented source 
Mil* in memory and that you have S)aved a copy of it on 
disk. 


I ‘ lufer the E)ditor, put a LST OFF at the end of your source 
• 1 1 If and ASM it * 

I i Ui'iiinvf* the LST OFF statement at the end of your program 

I ( I Ml port ant!) * 

i))nir the editor, select the D}rive with MERLIC^ in it and 
I ivpr then STRIP <RFTURN> . 

% V«ii I may now use the XREF and, XREF * XL procedures as 

MU r 1 t uf'd *1 hove . 

1 VI i I nHLR 

I t h t r, ui MIev causes a machine cycle count to be displayed 

^ diir I Mp, ,iN'K^iiUi! y. To use it you must run CYCLE TIMER using Che 

I *|( iihfdi' h:" (‘uiniTi.ind * This must be done PRIOR to loading Che 

luiMi r M I *1^', 1 nru it resets the file pointers. You muse type 

' I In ilruiM’d PR fH cummaud , then USER and then ASM. The cycle 

i I I . will lii» pi livted to the right of the comment field and 

ill I uui< Mil' E 1i i ; 
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5,0326 or 5"3326 or 5'\0326 

The first nufiiber displayed is the cycle count for the current 
Instruction and the last is the accumulated total (in 
decimal). The single quote indicates a possible added cycle, 
depending on certain conditions. If this appears on a branch 
Instruction then it indicates that one cycle should be added 
If the branch occurs. For non“branch ins true tio’ns ^ the single 
quote indicates that one cycle should be added if a page 
boundary is crossed. A double quote occurs only on branch 
instructions and indicates that two cycles should be added if 
the the branch is taken. (The CYCLE TIMER prograni has 
determined that the branch would cross a page boundary in 
this event-) 

There are four locations, $A03^$A06, that can be adjusted by 
the user. You may adjust the position at which the count will 
be printed, the number (2^ A, or 6) of digits in the 
accumulated total, the averaging default, apd the USR enable 
flag > 

The byte at $A03 contains a number 2 less than the column in 
which the cycle count will start printing. The count, 
however, is always printed after the comment. To have the 
count printed as far to the right as possible this byte 
should be set to the total nutnber of col^unns minvis the number 
(2,4 or 5) of digits in the accumulated total less 5. This is 
presently set to ^47 which is appropriately for a 80 column 
printer. 

The byte at $A04 should contain 5^0, $40 or 0 depending on 
whether you want 2, 4, or 6 digits in the accumulated total 
count. 

The byte at $A05 should contain either 0 or $60 depending on 
whether you want the Lndetermicable added cycles averaged in 
the total count or not. 

The byte at $A06 should be either 0 or $80 depending on 
whether you want the internal USK routine to be enabled or 
not. If the USR routine is enabled then the USR opcode will 
reset the accumulated total to zero. If $A06 contains $80 
then the USR opcode is handled just as Lf CYCLE itNEK is not 
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to 4 Iir H MM L 


II .. iniiHiM nil lows [tj we i^uggest using CYCLl: ['LMIliK with 

Mm |ii liir.M set aC 96 characters per line rather than the 
u 'u M ?h/l. This will allow assembly of Files ordinarily 
I im.iiM^mI Inr d'/l columns without having the timec data 
oo ( M«mv j hr lilies. Of course^ the byte at $A(i33 must be set 
>> I n^ ,I 1 n)M y . You must also set the number of colunii’ts foe Che 
MM H 1 .. t o 96 (location $A01b)* 

I iMJl I t. 

Ihl'< piugiom can be used to do the major portion of 
tru -1 lino ii\ a source file from the CBH ASSHMBLER64 to 
[|i Ml IN luMiLit . To use it, read the file into MERLIN with the 
M I XM; rmnaiand. Then use the EXEC command Co run 

I iMh II . ihn main conversion done by the program is to change 
Mh' characLcr set 1" (UC/graphlcs) used by the CBH 
A'/.I nih .1 .Kf)4 (which becotoes lower case in MERLIN) to the 
>haf li fi'i set 2" (bC/LC) used by MERLIN. Lower case 
•hn iMi'is Hire converted to UC until a comment or literal 
mMiu’. L' i|uoM':;) is met, Note that although MERLIN would 
hnjuj‘ iHisn for opcodes arid labels, it requires upper 
• lur I IN hi'K digits A-F. Literals (eg. I.DA which are in 

Ni In (he CliN ASS3IMHLER64 are properly lower case in MERLIN 
In u*,Minidilf: Mu! same code so they are not converted. 

Hir |i'.i‘iidM (^pco^lns .BYTE, .DBYTE, .PAGE, .LKlP, .END, -MAC, 
IN h, din;, VMl^ END, MAC, «<, and DA. Other pseudo 

M|«i iiilf’i uinl Mie "* lines will have to be hand converted 
•M Ml I' I ImM r f;yni:a:c is substantially different From that used 
Lv Ml FI Ml. Also the macro name in a -MAC definition will have 
In hi* MiHVi’i! to Mvn I.ABEL column. 

<'Ml M -liM-u [ ii iuj^M the macro variables ?l^?3 to ]l^]8 but the 
mu'I imiui i li.my.n MiHicros and macro calls to reflect the fact 
ilhii Nl III IN iiSMS ordinary labels to label lines in a macro 
Im< hfUioo (they .ire IochsI) and the cornmn^s used to seperate 
MiIm.I -mil I M' Id macro calls will have to be clianged to 

Mu ti-inMnhm-i II MM I hy MERLIN. 

in Nf I 
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This resets source pointers to the usual value of ^AOO and 
moves any source in memory dou^ to that point. This utility 
is Intended for use after one of the XREF programs or CHRGEN 
80, If desired. To use it just run it via the EXEC mode "G" 
command■ 

MISCELLANEOUS ROUTINES 

A number of subroutines are on the disk as SEQ files* These 
are often used routines and are intended as PUT files or to 
be appended to programs and modified' as desired. Most of 
them requite certain equates to have been defined, or local 
variables declared In a VAR statement* Read them for details 
on their usage. 

MERLIN AND THE C64 LINK 

MERLIN contains a version called MERLIN.L which Is compatible 
with the Richvale Telecommunications C6A LINK* To use it you 
must run the RELOCATOR 5*5 program on the C64 LINK disk and 
select PET EMULATOR mode* The Pet emulator Itself should 
NOT be run. Then type DLOAD "MERLINand RUN* 

If the C6^ LINK is used with a disk drive on the SERIAL port 
there Is total compatibility except for the lesser roeiiiory and 
the DATA 20 80-column card, which Is not compatible with the 
C6^ LINK* 

If Che C64 LINK is used with NON-SERIAL disk drives then some 
MERLIN functions such as the ERR (in the editor), CATALOG* 
and disk error reporting In general will not be available* 
To do a catalog you must exit to BASIC and issue the C6A LINK 
CATALOG command; then return to MERLIN with a SYS 32000, 

The USR opcode cannot be used with the ,C64 LINK due to memory 
conflicts * 

SOURCEROR will work IF it is run using HERLlN's RUN command, 
but will be considerably limited In oiemory available for its 
use. Also, there is some possibility of overwrite of the.C64 
LINK code, in which case the system will crasli* Therefore, 
it is NOT advisable to force continuation of disassembly with 
the Control-0 override- 
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Nn'ri';: ALL PROGRAiM MODIFICATIONS SHOULD BE HADE TO A COPY OF 
MERLIN 64. DO NOT MAKE CHANGES TO THE MASTER DISKETTE. 

CHANCING DISPLAY COLORS 

til orilec to change the background, border or character colors 
In Merlin 64, enter the folowlng: 

LOAD "MEE1LIN",8 

Al the prompt, enter; 

LIST 50 


It should appear as follows: 

50 DATAO,0,0,10,0,123,0,10,94,4,47,15,15,144 

till' last three data elements ate referenced on page 74 of the 
Mci'ltn 64 manual. These data elements (15,15 and 144) are 
I 111* default values for border, background and character 
I iilors used by Merlin 64. 

Mu' following chart shows the values that can be substituted 
I nr the BORDER and BACKGROUND colors: 


0 BLACK 
I WHITE 
RED 
1 CYAN 


4 PURPLE 

5 GREEN 

6 BLUE 

7 YELLOW 


8 OR-ANGE 

9 BROWN 

10 LT. RED 

11 DARK GREY 


12 MED. GREY 

13 LT. GREEN 

14 LT. BLUE 

15 LT. GREY 


Mu' Following chart shows the values that can be substituted 
I III the CKARAQTER color; 


144 BLACK 
•i WHITE 
red 

I ’i9 CYAN 


156 PURPLE 

30 GREEN 

31 BLUE 
158 YELLOW 


129 ORANGE 
L49 BROWN 
150 LT. RED 
152 GREY 2 


151 GREY 1 

153 LT. GREEN 

154 LT. BLUE 


I hull, if you wanted to have a black background and border 
with white characters, you would change Line 50 as follows: 

50 DATAO,0,0,10,0,128,0,10,94,4,47,0,0,5 
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Color TV sets are lls=Ued in their ability to place certain 
colors next to each other on the same line. Therefore, some 
color combinations may produce blurred Images. When you find 

system, save the BASIC program 
called HE^IN and Herlin 64 will then always boot with your 
color combination- ^ 

If you wish to have white characters on a black background 
when you are using the CHRGEH 80 utility, just put a SFO in 
memory locations $A04 and $A05. 

LOWER CASE ONLY ON PRINTOUTS 

a'"? printer interface card (such as 

CARDCO) doing an ASCII conversion before printout. This may 
not surface when running a program In BASIC, but appears if 
the firmware on the card is Incorrect. To solve this, enter; 

LOAD "MERLIN",8 

and add the following line to the program: 

65 POKE 41191,97 

Then list Line 60 which should appear as follows; 

60 DATA8,16,0,0,128,60,7,80,128,0,0,97.14,20,31 

Change the eleventh data element from 0 to 160, The new 
Line 60 should then appear as follows; 

60 OATA8,16,0,0,128,60,7,60,128,0,160,97,14,20,31 

After testing these changes to verify that they work with 
your interface card, save the BASIC program called MERLIN. 

Note that these modifications only work with Interface cards 
Chat do an ASCII conversion. Do not use these with straight 
throughput interfaces such as RS232 etc. 

For more information, see the TECHNICAL INFORMATION section 
pages 73 to 75. ’ 
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WMm: PUT FILES WITH MERLIN 6^ 

IJ your source file becomes too large to assemble In memory^ 
yuu can use the PUT opcode- Just divide your program Into 
Pil'd: Ions and save each section as a separate text file by 
Mil lug the W (WRITE TEXT FILE) command- The PUT opcode loads 
I lu!Se text files and "Inserts" them In the “'Master" source 
file at the location of the PUT opcode. 

The "Master" source file can contain source code, equates, 
tnneros, and ALL of your PUT opcodes- You cannot define a 
macro from within a PUT file, and you cannot call the next 
PUT file from within the current PUT file. Thus, all macro 
(l(*f initions and all PUT opcodes must be in the "Master” 
source file, 

Tiio following three programs (2 PUT files and the Master) 
will demonstrate the proper method for using PUT files. 
First, write a text file called FlLEl by using the W command. 
This will be used as the first PUT file in the Master file. 


1 

FILEI 

LDX 

fio 

2 

I.OOPl 

LDA 

STRINGljX 

] 


BEQ 

FILE2 



JSR 

CHROUT 



I NX 


U 


BNE 

LOOPl 

/ 

STRING1 

ASC 

"THIS IS FILEI",00 


Now write another text file (FILE2) with the W command. This 
will be the second PUT file used by the Master file. 


1 

FILE 2 

LDX 

ilQ 

> 

i,00P2 

LDi^ 

STRING2,X 

1 


BEQ 

DONE 

^1 


JSR 

CHROUT 

*> 


INX 


fl 


BNE 

L00P2 

/ 

DONE 

RTS 


II 

STRING2 

ASC 

"NOW ITS FILE2 


IIm* Master source is assembled and saved using the S (SAVE 
NtJlIRCH) command, followed by the 0 (SAVE OBJECT) command. 
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1 * MASTER SOURCE FILE * 



2 

ORG $8000 



3 CliROUT 

EQU $FFD2 



h 

PUT "FILEl" 



5 

PUT "FILE2" 



When the 

Master file is assembled, 

it will Look like this; 


1 * master source file * 


2 

ORG 

$8000 


3 CHROUT 

EQU 

$FFD2 


4 

PUT 

FILEl" 

8000: A2 

00 >1 FILEI 

LDK 

1)0 

8002: ED 

OD 80 >2 LOOP! 

LDA 

STRING 1,X 

8005: FO 

14 >3 

BEQ 

FILE2 

8007: 20 

D2 FF >4 

JSR 

CHROUT 

800A; E8 

>5 

im 


BOOB: DO 

F5 >6 

BNE 

LOOPl 

800D; 04 

C8 C9 >7 STRING! 

ASC 

"THIS IS FILEl",00 

8010: 03 

AO C9 D3 AO C6 C9 1 

CC 


8018: C5 

81 00 




5 

PUT 

■■FLLE2'' 

801B; A2 

00 >1 F1LE2 

LDX 

110 

8010; BD 

28 80 >2 L00P2 

LDA 

STRING2,X 

8020; FO 

06 >3 

BEQ 

DONE 

8022: 20 

02 FF >4 

JSR 

CHROUT 

8025; E8 

>5 

INX 


8026; DO 

F5 >6 

BNE 

LOOP2 

8028: 60 

>7 DONE 

RTS 


8029: CE 

GF D7 >8 STRING2 

ASC 

"NOW ITS FILE2",00 

8028: AO 

C9 DA D3 AO C6 C9 

CC 


8033: C5 

B2 00 



—End assembly, 55 bytes, Errors: 

0 

USING THE DSK COMMAND WITH 

merlin 

64 

This causes Herlin 64 to assemble 

the file directly to disk- 

It is 

used at the very 

start 

of a source file before any 

code Is 

generated- It will 

assemble all code to disk, using 

the specified filename, until it 

encounters another DSK or 

reaches 

the end of code- 

Since 

DSK saves the object code to 
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i! I sk, you do not have to use the 0 (SAVE OBJECT) command. 

L * DSK COMMAND FOR MERLIN 64 * 






2 


DSK 

"FILE ONE" 

;ASSEM TO DISK 





3 


ORG 

$8000 






4 

CHROUT 

EQU 

$FFD2 






5 

SCNKE^ 

EQU 

$FF9F 






6 

GETIN 

EQO 

$FFE4 


BO DO 

A2 

00 


7 


LDX 

ito 


B002 

BD 

ID 

80 

8 

LOOPl 

LDA 

STRINGl,X 


B005 

FO 

06 


9 


BNE 

SCANL 


aoo7 

20 

D2 

FF 

10 


JSR 

CHROOl 


fiOOA 

E8 



11 


INX 



80OB 

: DO 

F5 


12 


BNE 

LOOP! 


800D: 

: 20 

9F 

FF 

13 

SCANl 

JSR 

SCNKEY 


8010 

: 20 

E4 

FF 

14 


JSR 

GETIN 


8013 

t FO 

F8 


15 


BEQ 

SCANl 


8015 

: C9 

OD 


16 


CMP 

#$0D 

RETURN PRESSED? 

80 1 7 

: FO 

03 


17 


BEQ 

DONEl 

IF Y WE'RE DONE 

80 19 

: 4C 

OD 

80 

18 


JMP 

SCANl 

IF N GO BACK 

801C 

: 60 



19 

DONEl 

RTS 



801 D; 

1 D4 

C3 

C9 

20 

SlRINGl 

ASC 

"TRIS IS FILE ONE",00 

80201 

1 03 

AO 

C9 

03 . 

AO C6 C9 

GC 



8028; 

1 C5 

AO 

CF 

CE ( 

C5 00 








21 


DSK 

"FILE TWO" ; 

;ASSEM TO DISK 

80 2 E 

A2 

00 


22 


LDX 

#0 


80 .10 

BD 

4b 

80 

23 

L00P2 

LDA 

STRING2,X 


80 11 

FO 

06 


24 


BNE 

SC AN 2 


80 15 

20 

D2 

FF 

25 


JSR 

CHROUT 


80 18 

E8 



26 


INX 



80 19 

DO 

F5 


27 


BNE 

LU0P2 


80 18 

20 

9F 

FF 

28 

SCAN2 

JSR 

SCNKEY 


no O'. 

20 

E4 

FF 

29 


JSR 

GETIN 


804 I 

FO 

F8 


30 


BEQ 

SCANZ 


804 1 

C9 

OD 


31 


CMP 

//$0D 

RETURN PRESSED? 

804 1 

t'O 

03 


32 


BEQ 

D0NE2 

IF Y WE"RE DONE 

804/ 

4C 

3 8 

80 

33 


JMF 

SCANZ 

IF N GO BACK 

8 04 A 

60 



34 

D0NE2 

RTS 



804 8 

Cl*. 

CF 

D7 

35 

STRING2 

ASC 

"NOW ITS FILE TWO" ,00 

8041'. 

AO 

C9 

D4 

D3 AO C6 C9 

CC 



8084 

C5 

AD 

iVi 

L)7 CF 00 




1 hr 

1 .lh«^^nnt3 ly , 

92 

by tes ^ Errors: 

0 
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Ht:RLIN-6^ KULL S CHE EM EDITOR 

The file ED-O on the rterlin”6^ diskette is a very compact but 
powerful full screen editor. It is intended for use with the 
Video pak”BU 80 column card. It can be used in 40 columns but 
this limits the line length to 40 and thus does not allow for 
much commenting. 


INSTALLATION 

To set up the Full Screen Editor initially, use the G command 
from the EXEC mode and type ED <RETURN>. Once it has been 
loaded into memory, it can be accessed from the standard 
Merlin-64 e'ditor by using the USER command. 

The Full Screen Editor is much more sophisticated than the 
standard Commodore editor and^ as such, will require some, 
practice. For example, unlike the Commodore editor, you do 
not press Return to get a line accepted into the file. In 
fact. Return creates a new empty line. Therefore, if you 
just wanted to move the cursor down, you would use the cursor 
keys instead. The Merlin—64 Full Screen Editor is a what 
you see is what you get' editor, that is, your file Is 
identical to what you see on the screen. 

Instead of using the INST key to" create space for insertions, 
you just type while you are in the insert mode (indicated by 
an inverse I cursor) and room is automatically created for 
the new text. 

With the standard Commodore editor, you cannot move the 
cursor while you are inserting text. That is not the case 
with the Merlin-64 Full Screen Editor* All commands keys 
are accepted as commands, whether or not the insert mode is 
active. 




rnflMAMl) SUHMAKY 


I In* cammantJ structure follows tliat of the standard Merlin“64 
I'dlior as much as possible. Most comi^iands that are "global^ 
In nature use the same character as the "locai^ command, but 
Ihiv 4 ^ the Commodore key (C=) as a prefix. If you are already 
l.nniliar with the Merlin-64 editor then these commands will 
r.MMin very natural- 

f:ntJT[tOL COMMAI^DS 

(Line oriented and cursor moves) 

Ci‘RL-A Delete all characters from cursor to end 

CTKL-B . • ..Hove cursor to beginning of line 

(JTRL-D .-.Delete character under cursor 

CTRL-'F - , . - . . . . Find character typed next (recursive) 

Ci’RL-X .*.Toggle character insert mode 

{ri'RL-N Move cursor to end of line 

CTRL"R , , - . ... Retieve original line 

CTRL-W .I.Find next word (alphanumeric) 

CTRL^-X Cancel global exchange in progress 

]'L ... , . , Toggle character insert mode 

K3 ..Show memory status box 

I'b ..Move cursor to start of next line 

K/ Toggle lower case convert mods 

Cursor keys.Move cursor 

DKL Delete character to left of cursor 

liOHR Remember current line for recall by C- HOME 

INST . Toggle character Insert mode 

RlCrURH t ..Carriage return and insert new line 
























GLOBAL COMMANDS 


A 

C== B 
C= C 
C- F 
C- 1 
L 

€= N 
C- P 
C- R 
C= W 
Z 


. Select for cutting ail text frosa current line to end 

* * * ' * - Move to beginning of file, screen centered 

* . . . . Cut to clipboard (start select If first time) 

. * . . . . Find text (recursive) 

^ ' * ■ ■ ■ * ' ' ? « * - ■ • Insert new line at cursor 

' ' ' - » - Go to label In label column, or line number 

* * * • * • * * ■ Move to end of file, screen centered 

. Paste contents of clipboard at current line 

" ■ ' ' ‘ - Replace last line deleted with current line 
■ ' * - - ’ • * • - ■ - • ■ * " * Find word (recursive) 

‘ ' ' ■ * * ” - « • * ' Reprint screen^ screen centered 


C up/down cursor . » « , Cursor up 10 lines, screen centered 
C- LEFT/RIGHT CURSOR • Cursor down 10 lines, screen centered 


CTRL 
C= DEL 
HOi-iE 
C- FI . 


• * * * . - s ^ , , * □ . Produce a line of boxes 
- . Delete previous line (UNDO with C= FI then C= R) 

. Move to line of last HOME, screen centered 

■■**'*■“"*■*■ • Insert new line at cursor 


C= * 
C= - 

C= * 

C= <-" 


(asterisk) * . . . * . . Produce a line of asterisks 
(hyphen) * * . □ , ^ , Produce a line of dashes 
(equal) . ^ „ * * * , Produce a line of equal signs 
(comma) Move backward one page 
(period) . * . ^ p Hove forward one page 


(left arrow) * Returns to standard Merlin-6A editor 


CUT AND PASTE 

C’^ C begins the select mode and selects the line the cursor 
is on. After this, you must select further lines by using 
either the down cursor or F5 key. These can he cancelled 
with the up cursor key to the limit of the top of the screen. 
Any other key will cancel the select mode. 

Selected lines are shown in Inversei When you want to cut, 
type C— G again. The selected lines will be cut from the 
file and placed on the clipboard- 






















I ■ A y Gleets everything froin the current line to the end of 
Mm file* C will then cut the selected text and place it 
rtn Mie cliphoardi ^ny other key will cancel. This provides 
a iihiiple means of moving the entire file to the clipboard, 
asisiHiiing there is room (about 8K is the maximura). 

«> r will paste the current concents of the clipboard into 
the file at the current line containing the cursor* Only 
lull lines are moved* This does not change the contents of 
the clipboard, so this can be used to replicate a range of 
lines* 

If the P paste command is issued when a range is selected> 
iTiaC range will be replaced by the text on the clipboard* 
Text deleted in this manner is not recoverable. 


FIND TEXT and GOTO LABEL 

Ttie C- F command brings up a dialog box which asks for the 
t(‘Kt to find. It then finds the first occurrence of the text 
In the entire text file. The text can be anywhere on a line* 
After the first find, you can find the next occurrence by 
typing another C= F* 

The C= B and F3 corntnands each cancel the find mode, as does 
(he failure to find the text below the current line* This 
< outlnued find mode is indicated by one or more plus (+) 
Mgns preceding the line number at the top right corner of 
! ht* screen* The continued find starts from the line below 
the current line, so it locates only one □ccurrence per line. 

I In? C= W command is identical to the C- F command except it 
I [itds only whole words which are bounded by non-alphanumeric 
• thiracters. If you type either C= W or C= F to find the 
Mi»xt occurrence, this mode will change aGCordingly. 

I I you use the C= W, G- F, or C= X commands after you have 
it'UMl the C- C or down cursor key to select a range, then 
'Hilv the selected range will be searched. Otherwise the 
f'lirfre file will be searched. These commands will cancel 
Mu' ru'iecc mode. 




The C= L command asks for a label to locate (any text can be 
used)* It then locates the fitst occurrence of that text in 
the file, but only in the label column. Only the characters 
typed are compared with the labels, so in some cases you may 
wish to end the "text to find" with a space. 

The Intended use for this command is to move rapidly to a 
particular place in the file- You can use "markers" to 
enhance the capability of this command- Thus if a line 
starts with a 7" then you can specify 7" as the text 
to find with this command- If you type a number for the 
label in a C= L command, you will be sent to that line 
number* This is particularly useful when editing a file 
using a printed listing. 

In all cases, the line containing the text found will be 
centered on the screen, unless it is within the first few 
lines of the file* 


GLOBAL EXCHANGE 

The G= X command produces a dialog box that asks for the text 
to change, and the new text to replace it* If you just type 
RETURN for either of these, the command is aborted, and then 
the file is searched for the text to change. Unlike the C= F 
find command, it looks only for full words* That is, the 
text found must be bounded by non^alphanumetic characters or 
it will be ignored* 

If text is found with this method, the screen is reprinted 
with the replacement made and the cursor is placed on the 
first character of the replacement. Now you must press a key 
to continue- Pressing Return or any other control characters 
will defeat the change and the routine will look for the next 
occurrence of the text to change. Pressing the space bar or 
any other character will cause all occurrences to be changed. 

One exception to this is CTRL-X, which will abort the process 
and return control to you- The other exception is the "A" key 
which causes all occurrences to be changed- Caution: once 
you have pressed the "A" key, you will not be able to abort 
this command. 






Vou can tell when the routine is finished by the fact that 
the line namher at the top right of the screen is missing 
diiring the exchange sequence and will return when there are 
no more matches for the change text, or until you press 
c:trL“X - 


REPLACE LII^E and DELETE LINE 

The C= D and C- DEL commands delete a line from the file and 
place it in a special "undo" buffer, which is independent of 
the clipboard- The C= R command exchanges the current line 
with this undo buffer* Thus^ two successive R commands 
will cancel out one another* C= R on an empty line places 
the undo buffer at that line and clears the undo buffer. 

Note that these commands can be used to move a single line to 
another location* To accomplish this, place the cursor on 
the line to be moved and type D and then move the cursor 
to an empty line or anywhere else* Now press either RETURN 
or C” FI to create an empty line, and then type C= R* 

C“ R can be used by itself to easily interchange two lines* 
vUist place the cursor on the first line, press C= R, move 
the cursor to the second line, press C== R again, then move 
l\\G cursor back to where the first line was and press C= R 
lor the third, and final, time- 

FAST CURSOR MOVES 

Ttif‘ left/RIGHT CURSOR cammand moves the cursor ten lines 
holow its current cursor position, and then reprints the 
•iciaen so Chat the cursor will be on the eleventh line. If 
tills command is repeated, it has the effect of moving the 
‘ ni rent line to the top of the screen and then moving the 
cursor to the eleventh line on the screen* 

himllarly repeating the C” UF/DOWN CURSOR command moves the 
I up line to the eleventh line on the screen and puts Che 
• nI nor on that line* The C= , and C= * commands move up or 
duwn one page at a time* They are roughly equivalent to two 
MUfcussive C” CURSOR commands. 




STATUS 


The F// command displays a status box showing the number of 
used and free bytes, and die length of the clipboard If any. 


CHARACTER INSERT HODE 

The character insert oiode defaults to ON upon entry* When 
you change it with the FI (or CTRL-I or INST) key, It remains 
that Way until changed again* Thus, moving from one line to 
another has no effect on this status* 

The status Is Indicated by the cursor type, which is an 
inverse I when the insert mode is on, and is an Inverse 
space when it is off* The cursor is an inverse 'F' when you 
are in the Find mode* 


LOWER CASE TOGGLE 

Ordinarily, unless the cursor is In a comment or ascii 
string, lower case characters will be converted to upper 
case characters. This is also defeated when the tabs are 
zeroed. To override this conversion, or to reinstate it, 
use the F7 command. This conversion is also in effect when 
you use the C= F, C- W, or C- L commands- 


LINE NUMBER and EOL MARKER 


At the upper right hand corner of the screen, the number of 
the line containing the cursor is printed. Somewhat to the 
left of this you may see a left bracket- This indicates the 
position at which an assembly listing will overflow the 
printer line. 


You can put characters beyond this mark, 
infomiation only. The position of the 
using your line Length parameter in the 
very large, the mark will not be shown. 


since it is for 
mark Is calculated 
FARMS. If this is 







Cl^NERAL NOTliS 


When you movu the cursor betwceu lines, its horizontal 
position will jump around. This is because it is based on 
the actual position in the line rather than Che actual screen 
position. 

If the tabs are zeroed you will not notice this, except for 
the fact chat the cursor is never beyond the last character 
in the line. Thus, a short line may move it to the left. 
Tabs can only be set in the standard Merlin“64 editor, so you 
must return to that editor if you wish to reset them. 

The maxiniura line length is 80 characters. Lines longer than 
this will be truncated when and if they are edited. 

You must return to the standard editor (C= in order to 
access the asseinbler, the SXEC mode, the monitor, etc* 

Unlike the standard Kerlin^64 editor, the CTRL-A key in the 
Full Screen Editor does not move to the next line after 
deletion of characters from the cursor on. This makes it 
possible to use the CTRL-R key to undo this command. 

An assembly will delete the contents of the clipboard. 


MEMORY USAGE 

I'he Merlin-64 Full Screen Editor uses 13 pages (3.25K) from 
tlie bottom of the source file memory. The clipboard is 
located under the ROMS and remains intact until an assembly 
Is done, which clears the contents of the clipboard. The 
clipboard is not effected by file loads. - 

(JOPS 

Virtually any Full Screen Editor command can be undone. You 
fihould remember that the proper undo consmand is of the same 
type" as the command you want to undo. 







Hit exninpie ^ line editing coraiuands are 
Tills inclLirJes the C" C= CTRL C= - 
which are regarded as line ed 11IngCommands 


undone by CTRL-R, 
and C= = commands 
for this purpose* 


The line deletion commands C= D 
creating an empty line with C= 
you forget to create the empty 
and then start again* 


and C= DEL are undone by 
FL and then typing C" R* If 
line, just type another C= R 


The C- R command undoes Itself* 

A CUT is undone by a PASTE without moving the cursor off its 


TECHNICAL NOTES 


The Herlin-64 Full Screen 
certain parameters can be al 


Editor has been arranged 
tered with little effort. 


so 


that 


i load address of the file is SAOU, which will be refer 
as START. START begins with a JMP 


At START + 3, there is a vector intended for expansion 


At START + 5, there are the characters used for 
cursors. These are an Inverse I, F, space, and 
F s depend on the state of the insert mode, 
any characters you want here, but there is no 
characters will work well. 


four possible 
F; the two 
You can change 
guarantee all 


At START + 9 is the byte SAO which is Che blink cate. ' By 
Increasing this value. you can make the blinking slower. 

Value 0 giveSthe slowestrate. 


At START + 10 is a table of command characters 
the C- key* Some cursor moves and RETURN 
separately and are not In these tables. This 
with a zero. 


used without 
are handled 
table ends 


■IS is followed immediately by the table of key commands 
ed with the €=• key, again ending with a zero 





MERLIN 

By Glen Brecion 



What kind of assembler would you 
expect from a company recognized as 
the programming utility experts? Simply 
the best, of course. MERLIN64 Is more 
than just an assembler. It is an extremely 
powerful yet easy to use macro 
assembler, with a very sophisticated 
editor, combined with many additional 
files and programming utilities into a 
truly remarkable package. 

In addition to all of the common features 
you would expect, the MERLIN64 
assembler allows such enhancements as 
the optional writing of object files to 
disk, and linking files to assemble source 
listings otherwise too large to fit into 
memory at once. MERLIN64 can read 
and write text files as well as binary 
source files, 

The macro feature of MERLIN64 ciilows 
you to give a simple name to often used 
routines in a source listing. Then you 
need only enter the name of the macro 
when entering further text. 

MERL1N64 contains a Beginner's Guide 
tutorial to familiarize the novice with 
assembly language programming using 
MEEILIN64* MERLlN64’s five modules, 
(Executive, Editor, Assembler. Symbol 
Table Generator, and Monitor) contain 
over 100 commands to speed program 
development and simplify your 
programming needs. 

In addition to the versatile MERLIN64 
assembler, the package also contains 
many additional utilities, including: 

SOURCEROR: 

Generates pseudo source code from 


raw binary data, Automaticaliy assigns 
labels to all recognizable addresses in 
a binary file. Addresses are fouiul In a 
table which SOURCEROk urieifiKCs 
during the disassembly process, Tfie 
label file can also be edited to kvclude 
your own labels as you desire. 

MACRO LIBRARYs 

A library of commonly used macro 
definitions and fundamental operations. 
Sample macro programs provide 
guidance to the novice on macros and 
how they can be used with an assembly 
program. 

XREFj 

A utility' program that provides a 
convenient means ofgeneratlng a cross- 
reference listing of aJl labels used with 
a MERLIN64 source program. 

CKRCEN SO: 

An optional SO-column character 
generator designed specifically to allow 
the use of MERLIN 64 with an 80 column 
by 24 line display. Because of resolution 
requirements, this feature Is for use with 
display monitors only, not television 
sets, 

FORMATTER: 

Enhances the use of MERliN64 as a 
general text editor. FORMATTER 
automattcally formars a file into 
paragraphs using specified line lengths. 

The MERLIN64 user manual Is easy to 
read, contains an Index, Memory Map 
information, and a complete Glossary 
for quick and easy reference. 


MERLIN64 requires a Commodore 64 and a disk drive. 
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